If Adyen cannot reach your server to deliver a webhook message, the webhook is placed in a retry queue to give you time to resolve the issue. Use this guide to troubleshoot and resolve webhook delivery failures using the tools in your Customer Area.
Retry queue
If you do not accept a webhook message by responding with a successful HTTP status code, we consider the webhook delivery a failure and set the webhook status to Failing. Adyen retries sending the webhook message three times immediately, then the webhook is placed in a retry queue. Retry queues are separate for each webhook endpoint. If you have multiple endpoints, you must troubleshoot them individually.
From the queue, we automatically retry sending the webhook for up to 30 days. After the first three failed retries, we retry sending the webhook in the following intervals:
- 2 minutes
- 5 minutes
- 10 minutes
- 15 minutes
- 30 minutes
- 1 hour
- 2 hours
- 4 hours
- 8 hours
If a retry is successful, we continue with the next webhook in the queue.
Troubleshoot failures
- In your Customer Area, go to Developers > Webhooks.
- Find the webhook endpoint with a Failing status and select it.
- Select Troubleshoot to view the list of failed webhook messages for that endpoint. Each failed event includes an error message and a timestamp.
This video shows how to find and troubleshoot failing webhooks:
The error message can help you diagnose the issue. The exact meaning depends on your server setup, but here are some common errors based on standard HTTP response codes:
| HTTP Error | Potential Cause | Recommended Action |
|---|---|---|
| 401: Unauthorized | Your server is refusing the connection due to invalid credentials. | Check that your webhook security (basic authentication or HMAC) is set up correctly. Consider rotating credentials if they have been compromised. |
| 404: Not found | The webhook URL could not be reached. | Ensure the endpoint URL is correct, publicly accessible, and not blocked by a firewall. |
| 422: Unprocessable content | Your server received the webhook but your business logic rejected it. | This can be due to validation logic on your endpoint. We recommend acknowledging receipt with [200 OK] first, and performing business logic separately. |
| 429: Too many requests | Your server is rate-limiting requests from Adyen. | This can happen after you fix a failing endpoint, as the queued webhooks are sent in a short timeframe. Ensure your server can handle the load. |
| 500: Internal server error | A generic error occurred on your server. | Check your server logs to identify the root cause. Ensure the endpoint is available and the application is running correctly. |
Multiple Adyen products use webhooks. Successfully receiving one type of webhook (for example, for a payment authorisation) does not guarantee successful delivery of all types. Always use the Troubleshoot tool for reliable diagnostics.
Resolve failures
From the Troubleshoot page for a failing webhook, you can manually intervene:
- Retry: After you deploy a fix, manually send the webhoom message to your server again.
- Ignore: If a webhook is no longer needed, permanently remove it from the queue.
After you have identified the cause of the failure and deployed a fix to your server:
- Navigate to the failed webhook event as shown in Step 1.
- Select Retry to send the webhook to your endpoint again. A success message indicates your endpoint has accepted it. If it fails, you will get a new error message.
- If the webhook event is outdated or no longer relevant, select Ignore. The event is permanently removed from the queue and cannot be retried.
Set up failure alerts
You can receive alerts by email or in the Customer Area notification center when webhooks fail. Adyen sends the following types of alerts:
- Initial Failure: Receive an alert when we detect that your webhook endpoint is consistently failing to accept events. Adyen sends an alert after 5 retry attempts.
- Ongoing Failure: Get notified if a failing endpoint remains unresponsive for an extended period. Adyen sends an alert after 7 days of a webhook failing.
- Recovery: Adyen informs you when a previously failing webhook endpoint successfully starts accepting events again.
To configure alerts:
- In your Customer Area, go to Notification center > Settings.
- Under Developers and Integrations, find the topic Webhooks.
- Use the toggles to enable or disable Email or Notification center alerts.
When the Email toggle is enabled, email notifications are sent to the email address linked to your user.