Secure webhooks

When configuring webhooks for your Adyen implementation, consider the following security recommendations to ensure the messages you receive about events are from Adyen, and were not modified during transmission to you.

Authentication / Authorization

We also recommend that you use an authentication mechanism for access to your webhook endpoints to ensure the webhook events you receive were sent by Adyen.

You can use one of the following authentication mechanisms for webhook endpoint access:

• Open Authorization (OAuth 2.0): strongly recommended and supported for the Standard webhook type
• Basic Authentication: supported for all Adyen webhook types

Open Authorization (OAuth 2.0)

Note: OAuth 2.0 support is available for the Standard webhook type only.

We strongly recommend that you use OAuth 2.0 for the Standard webhook type. OAuth 2.0 is a much safer option than basic authentication, ensuring that your server credentials are not compromised.

With an OAuth 2.0 implementation, Adyen requests an OAuth 2.0 access token for sending webhook events to your webhook endpoint. After Adyen obtains an access token from your OAuth 2.0 Identity Provider's authorization server, we send the access token in the header of each webhook event, so you can authenticate the request with your webhook server endpoint.

To set up OAuth 2.0 for the Standard webhook type in your Customer Area, you must provide the following:

• Client ID
• Client secret - Make sure to protect your client secret and never embed it in client-side code, as this would expose it to potential misuse.
• URL: The location of your OAuth 2.0 Identity Provider's authorization server where Adyen should request new access tokens.
  At a minimum, the time-to-live (TTL) setting of your access tokens must be one hour (3599 seconds).
• Scope: The permission level that Adyen's webhook service needs to access your webhook endpoint.
  We strongly encourage you to follow the principle of least privilege when creating scopes. Only grant the permissions that are absolutely necessary for your integration.

We recommend that you rotate your OAuth 2.0 client credentials periodically to proactively reduce risk and maintain the highest level of security.

Basic authentication over HTTPS

For all webhooks types other than the Standard webhook type, we recommend that you use basic authentication over HTTPS.

Note: You can use basic authentication over HTTPS instead of OAuth 2.0 for the Standard webhook type. However, basic authentication can leave your server more vulnerable to compromise.

After you have set up a username and password for basic authentication in your Customer Area, we include these in the header of the webhook event, so you can authenticate the request with your server. To ensure basic authentication is secure, you must use HTTPS for your webhook endpoint; otherwise your basic authentication credentials can be compromised.

Hash-based message authentication code (HMAC) signatures

To protect your server from unauthorized webhooks, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. By verifying the signature included in a webhook event, you confirm that the event was sent by Adyen, and was not modified during transmission. For more information, refer to Verify HMAC signatures.

Changing your HMAC key

If you need to change the secret HMAC key used to sign webhook events, it is enough to generate a new HMAC key in your Customer Area.

If you generate a new HMAC key, it can take some time to propagate this in our infrastructure, so make sure that you can still accept webhook events signed with your previous HMAC key for some time.

Domain and IP addresses

Depending on your network and security requirements, you might need to add Adyen's network to your firewall's allowlist to receive webhook events from us.

We do not provide a list of IP addresses. IP addresses change over time due to various reasons, such as ISP configuration changes. This can lead to disruptions in receiving webhooks if IP addresses are hard-coded.

To make sure you can communicate with our network, you can either:

• Use a domain allowlist. Include our domain out.adyen.com if your network configuration allows domain allowlisting.
• Systematically resolve our IP addresses. Perform DNS lookup for out.adyen.com. We recommend that you check every hour. However, if you choose to hardcode the resolved IP addresses to an allowlist, you still run the risk of a disruption if IP addresses change during the DNS lookup interval.