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.
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
- Log in to your Customer Area.
- Go to Developers > Webhooks.
- In the row of the webhook for which you want to change the endpoint, select the edit webhook icon .
- Under Server configuration, configure the following fields:
- URL: Enter your HTTPS URL.
- Encryption Protocol: Select TLSv1.2 or TLSv1.3.
- Select Save changes.
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:
- Log in to your Customer Area.
- Go to Developers > Webhooks.
- In the row of the webhook you want to disable, select the edit webhook icon .
- Clear the Active checkbox.
- Select Save changes.
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.
If you change the URL while the webhooks are disabled, you will not receive the queued webhook events, because these will be sent to the old URL.
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.
- Log in to your Customer Area.
- Go to Developers > Webhooks.
- In the row of the webhook you want to edit, select the edit webhook icon .
- Under Merchant Accounts, select one of the following options:
- Include All to apply the webhook settings to all merchant accounts.
- Include Accounts to apply the webhook settings only to the accounts you choose.
- Exclude Accounts to not apply the webhook settings to the accounts you choose.
- Select Save changes.
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.