Manage webhooks

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'll 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. With your company account selected, go to Developers > Webhooks.
3. Select Platforms to view the webhooks that are configured for your platform.
4. Select Edit webhook next to the webhook you want to update.
5. Under Server configuration, configure the following:
   • URL: Enter your HTTPS URL.
6. Select Save configuration.

Change your endpoint and disable your old endpoint for receiving webhooks:

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

Disable webhooks

You might 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 for webhooks.

To disable a webhook:

1. Log in to your Customer Area.
2. With your company account selected, go to Developers > Webhooks.
3. Select Platforms to view the webhooks that are configured for your platform.
4. Select Disable webhook next to the webhook you want to update.

In the list of webhooks, Disabled appears in the Status column for the webhook. When you disable a webhook, Adyen queues all webhook events intended for 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.

Disabled webhooks are automatically removed from the Webhooks page after six months.

Delete webhooks

Before you decide to delete a webhook, consider whether you have received all events that were scheduled to arrive to your server. When you are certain you no longer need the webhook, you can safely delete the webhook configuration.

To delete a webhook configuration:

1. Log in to your Customer Area.
2. With your company account selected, go to Developers > Webhooks.
3. Select Platforms to view the webhooks that are configured for your platform.
4. Select Delete webhook next to the webhook configuration you want to delete.
5. Select Delete to confirm your selection.

Queued webhooks

To ensure that webhook events are properly delivered, your server should acknowledge them with a 200 level HTTP response.

If we do not receive the response within 10 seconds, the webhook configuration will be put in a failing state. This will cause all new webhook events for that endpoint to be queued.

Adyen will retry sending the webhook event until it is accepted. You can also manually retry the event using the Troubleshoot functionality in the Customer Area. Once accepted, events in the queue will be resent.

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.

Troubleshoot

If your server does not respond to a webhook in ten seconds with a 200 level HTTP response, Adyen changes its status to failing. In the Customer Area, you can view your the status of your webhooks, and logs from those webhook's events. To troubleshoot, retry the events then check the logs to see how your server responded.

To access the list of webhooks that encountered an error during delivery in the Customer Area:

1. In the Customer Area go to Developers > Webhooks.
   Webhooks that we didn't successfully deliver to your server have a Failing status.
2. From the list, select the webhook with the Failing status.
3. To view and retry the stuck event, select Troubleshoot.

Additionally, you can view a log of your webhook events from the last seven days:

1. Log in to your Customer Area and stay on the company account.
   Webhook event logs for a balance platform integration are available on the company account.
2. Go to Developers > Event logs.
3. Select an item to see its details. You will see the timestamp, your webhook endpoint URL, the PSP reference or resource ID, and the request and response bodies.

These tools allow you to send retries to your server and view the result, which can be either a success or an error. The exact meaning of an error message depends on how your server is set up. If you are using HTTP response codes in the standard way, some common errors and their meanings are:

• 401: Unauthorized. Your server is refusing the connection due to invalid credentials. Make sure basic authentication and HMAC are set up properly and consider rotating the credentials.
• 404: Not found. Your endpoint could not be accessed. Make sure your endpoint is accessible over a network and there are no firewall rules that block incoming traffic.
• 422: Unprocessable content. Your endpoint was accessed but your business logic denied processing the event. This could be due to validation logic on your endpoint. Make sure the event is accepted first before applying any validation. Adyen recommends accepting every webhook and performing business logic related to its contents after.
• 429: Too many requests. Your endpoint was accessed but your server is "rate limiting" the requests. This can happen after you fix a failing webhook because all of the queued webhook events get sent in a short timeframe.
• 500: Internal server error. This is usually a generic error from your server. Check that the endpoint is available and the route is accepting traffic.