Best practices

Security

To protect your server from unauthorised webhooks, we strongly recommend that you use Hash-based message authentication code (HMAC) signatures. By verifying the signature included in a webhook, you will confirm that the webhook 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, so you can authenticate the request with your server. For this to be secure, you need to use HTTPS for your webhooks endpoint, otherwise your basic authentication credentials can be compromised.

Change your HMAC key

If you need to change the secret HMAC key used to sign webhooks, you can generate a new HMAC key in your Customer Area.

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

Configure your existing webhook endpoint

You can change the endpoint of your existing webhook.

Update your endpoint URL

1. Log in to your Customer Area.
2. Go to Developers > Webhooks.
3. Select the kebab menu (⋮) next to the webhook you want to update.
4. Under Server configuration, configure the following field:
   • URL: Enter your HTTPS URL.
5. Select Save configuration.

To change your endpoint and disable your old endpoint for receiving webhooks:

1. Add a new endpoint in your Customer Area.
2. Disable the old endpoint.

Disable and delete a webhook

You might want to disable a webhook when:

• Your webhook endpoint is temporarily unable to receive webhooks, for example during server maintenance.
• You have set up a new webhook endpoint for webhooks.

To disable a webhook:

1. Log in to your Customer Area.
2. Go to Developers > Webhooks.
3. Select the kebab menu (⋮) next to the webhook you want to disable.
4. Select Disable webhook in the dropdown menu.
5. Select Disable to confirm.

In the list of webhooks, you will see the status Disabled next to the webhook. 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 Enabled toggle.

If you change the URL while the webhooks are disabled, you will not receive the queued webhooks, as these will be sent to the old URL.

To delete a webhook:

1. Log in to your Customer Area.
2. Go to Developers > Webhooks.
3. Select the kebab menu (⋮) next to the webhook you want to delete.
4. Select Delete webhook in the dropdown menu.

Queued webhooks

To ensure that webhooks are properly delivered, your server should acknowledge them with an appropriate response message.

If we do not receive the response message within 10 seconds, all webhooks to this endpoint will be queued.

We will retry sending the webhook until it is accepted. Once accepted, you will also receive all the queued webhooks.

Retry attempts happen regularly for up to 7 days, at increasing time intervals:

• 2 minutes
• 5 minutes
• 10 minutes
• 15 minutes
• 30 minutes
• 1 hour
• 2 hours
• 4 hours

After that, retries happen every 8 hours for the following 7 days.

The webhook queues are maintained separately for each endpoint. If you have multiple endpoints for receiving webhooks and we have queued webhooks for one of them, this won't affect the remaining endpoints.