Security
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.
We also recommend that you use basic authentication over HTTPS. 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. For this to be secure, you need to use HTTPS for your webhook endpoint, otherwise your basic authentication credentials can be compromised.
Basic authentication only guarantees that the webhook event was sent by Adyen, not that it wasn't modified during transmission.
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.
Creating new webhooks
You can create webhooks for your company account, merchant account, and merchant account groups.
We strongly recommend to create webhooks on the company account level. To configure a webhook for a specific merchant account, create a webhook for your company account, and configure merchant accounts to include or exclude merchant accounts from that webhook's configuration. This ensures that you do not have duplicate webhook configurations, and improves performance.
For improved performance, we also recommend to limit the number of webhooks you configure for each company account.
Configuring your existing webhook endpoint
You can change the endpoint of your existing webhook.
Adyen requires you to use HTTPS endpoints with a compatible TLS configuration to receive Adyen webhook events. Before you configure your endpoint to receive Adyen webhook events, you need to make sure it supports connections using the correct TLS version and cipher suite.
Update your endpoint URL
-
In your Customer Area, go to Developers > Webhooks.
-
From the list of webhooks, select the one to configure.
-
Select Edit webhook or the edit icon .
-
Under Server configuration, configure the following:
Setting Description URL Your webhook server's URL. It must be a public URL. Method JSON, HTTP POST, or SOAP Encryption protocol TLSv1.2 or TLSv1.3 -
Select Save configuration.
If you want to change your endpoint and disable the old endpoint for receiving webhooks:
Disabling webhooks
You may want to disable webhooks when:
- Your webhook endpoint is temporarily unable to receive webhooks, for example during server maintenance.
- You have set up a new webhook endpoint.
To disable webhooks:
- In your Customer Area, go to Developers > Webhooks.
- From the list of webhooks, select the one to disable.
- Under General, deselect the Enabled toggle to disable it.
- Select Save configuration.
We will then queue all webhook events to this endpoint. You will receive the queued webhook events when you reactivate this endpoint by selecting the Active checkbox.
Configurations that have been inactive for more than six months will be automatically deleted.
Configuring merchant accounts
If you are on your company account, you can configure webhook settings for a group of merchant accounts or for all merchant accounts.
- In your Customer Area, go to Developers > Webhooks.
- From the list of webhooks, select the one to configure.
- Select the either Edit webhook or the edit icon .
- Under General, select one of the following options from the Merchant Accounts dropdown menu:
- All merchant accounts to apply the webhook settings to all merchant accounts.
- Include only specific merchant accounts and select the merchant accounts to include.
- Exclude specific merchant accounts and select the merchant accounts to exclude.
- Select Save configuration.
Handling duplicates
In some cases it is possible that you receive the same webhook event twice, so make sure that your system is able to deal with duplicates. These duplicate webhook events have the same values in the eventCode and pspReference fields, while the eventDate and other fields can be different. Your server should use the details from the latest webhook event.