{"title":"Troubleshoot webhooks","category":"default","creationDate":1779620072,"content":"<p>If Adyen cannot reach your server to deliver a webhook message, the webhook is placed in a <a href=\"#retry-queue\">retry queue<\/a> to give you time to resolve the issue. Use this guide to <a href=\"#troubleshoot\">troubleshoot<\/a> and <a href=\"#resolve-failures\">resolve webhook delivery failures<\/a> using the tools in your Customer Area.<\/p>\n<h2 id=\"retry-queue\">Retry queue<\/h2>\n<p>If you do not <a href=\"\/development-resources\/webhooks\/handle-webhook-events#accept-webhooks\">accept a webhook message<\/a> by responding with a successful HTTP status code, we consider the webhook delivery a failure and set the webhook status to <span translate=\"no\"><strong>Failing<\/strong><\/span>. Adyen retries sending the webhook message three times before placing the webhook into a retry queue. The initial delivery attempts are sent at 9 seconds, 18 seconds, and again at 27 seconds. Retry queues are separate for each webhook endpoint. If you have multiple endpoints, you must troubleshoot them individually.<\/p>\n<p>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:<\/p>\n<ul>\n<li>2 minutes<\/li>\n<li>5 minutes<\/li>\n<li>10 minutes<\/li>\n<li>15 minutes<\/li>\n<li>30 minutes<\/li>\n<li>1 hour<\/li>\n<li>2 hours<\/li>\n<li>4 hours<\/li>\n<li>8 hours<\/li>\n<\/ul>\n<p>If a retry is successful, we continue with the next webhook in the queue.<\/p>\n<h2 id=\"troubleshoot\">Troubleshoot failures<\/h2>\n<ol>\n<li>In your <a href=\"https:\/\/ca-live.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, go to <strong>Developers<\/strong> &gt; <strong>Webhooks<\/strong>.<\/li>\n<li>Find the webhook endpoint with a <span translate=\"no\"><strong>Failing<\/strong><\/span> status and select it.<\/li>\n<li>Select <strong>Troubleshoot<\/strong> to view the list of failed webhook messages for that endpoint. Each failed event includes an error message and a timestamp.<\/li>\n<\/ol>\n<p>This video shows how to find and troubleshoot failing webhooks:<\/p>\n<iframe src=\"https:\/\/player.vimeo.com\/video\/843200501\" width=\"640\" height=\"360\" frameborder=\"0\" webkitallowfullscreen mozallowfullscreen allowfullscreen><\/iframe>\n<p>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:<\/p>\n<table>\n<thead>\n<tr>\n<th style=\"text-align: left;\">HTTP Error<\/th>\n<th style=\"text-align: left;\">Potential Cause<\/th>\n<th style=\"text-align: left;\">Recommended Action<\/th>\n<\/tr>\n<\/thead>\n<tbody>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>401: Unauthorized<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Your server is refusing the connection due to invalid credentials.<\/td>\n<td style=\"text-align: left;\">Check that your <a href=\"\/development-resources\/webhooks\/secure-webhooks\">webhook security<\/a> (basic authentication or HMAC) is set up correctly. Consider rotating credentials if they have been compromised.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>404: Not found<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">The webhook URL could not be reached.<\/td>\n<td style=\"text-align: left;\">Ensure the endpoint URL is correct, publicly accessible, and not blocked by a firewall.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>422: Unprocessable content<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Your server received the webhook but your business logic rejected it.<\/td>\n<td style=\"text-align: left;\">This can be due to validation logic on your endpoint. We recommend acknowledging receipt with <code>[200 OK]<\/code> first, and performing business logic separately.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>429: Too many requests<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">Your server is rate-limiting requests from Adyen.<\/td>\n<td style=\"text-align: left;\">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.<\/td>\n<\/tr>\n<tr>\n<td style=\"text-align: left;\"><span translate=\"no\"><strong>500: Internal server error<\/strong><\/span><\/td>\n<td style=\"text-align: left;\">A generic error occurred on your server.<\/td>\n<td style=\"text-align: left;\">Check your server logs to identify the root cause. Ensure the endpoint is available and the application is running correctly.<\/td>\n<\/tr>\n<\/tbody>\n<\/table>\n<div class=\"notices green\">\n<p>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 <strong>Troubleshoot<\/strong> tool for reliable diagnostics.<\/p>\n<\/div>\n<h2>Resolve failures<\/h2>\n<p>From the <strong>Troubleshoot<\/strong> page for a failing webhook, you can manually intervene:<\/p>\n<ul>\n<li><strong>Retry<\/strong>: After you deploy a fix, manually send the webhook message to your server again.<\/li>\n<li><strong>Ignore<\/strong>: If a webhook is no longer needed, permanently remove it from the queue.<\/li>\n<\/ul>\n<p>After you have identified the cause of the failure and deployed a fix to your server:<\/p>\n<ol>\n<li>Navigate to the failed webhook event as shown in <a href=\"#find-and-diagnose-failures\">Step 1<\/a>.<\/li>\n<li>Select <strong>Retry<\/strong> 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.<\/li>\n<li>If the webhook event is outdated or no longer relevant, select <strong>Ignore<\/strong>. The event is permanently removed from the queue and cannot be retried.<\/li>\n<\/ol>\n<h2 id=\"webhook-alerts\">Set up failure alerts<\/h2>\n<p>You can receive alerts by email or in the Customer Area notification center when webhooks fail. Adyen sends the following types of alerts:<\/p>\n<ul>\n<li><span translate=\"no\"><strong>Initial Failure<\/strong><\/span>: Receive an alert when we detect that your webhook endpoint is consistently failing to accept events. Adyen sends an alert after 5 retry attempts.<\/li>\n<li><span translate=\"no\"><strong>Ongoing Failure<\/strong><\/span>: Get notified if a failing endpoint remains unresponsive for an extended period. Adyen sends an alert after 7 days of a webhook failing.<\/li>\n<li><span translate=\"no\"><strong>Recovery<\/strong><\/span>: Adyen informs you when a previously failing webhook endpoint successfully starts accepting events again.<\/li>\n<\/ul>\n<p>To configure alerts:<\/p>\n<ol>\n<li>In your <a href=\"https:\/\/ca-test.adyen.com\/\" target=\"_blank\" rel=\"nofollow noopener noreferrer\" class=\"external-link no-image\">Customer Area<\/a>, go to <strong>Notification center<\/strong> <i class=\"adl-icon-alert\"><\/i> &gt; <strong>Settings<\/strong>.<\/li>\n<li>Under <strong>Developers and Integrations<\/strong>, find the topic <strong>Webhooks<\/strong>.<\/li>\n<li>Use the toggles to enable or disable <strong>Email<\/strong> or <strong>Notification center<\/strong> alerts.<\/li>\n<\/ol>\n<p>When the <strong>Email<\/strong> toggle is enabled, email notifications are sent to the email address linked to your user.<\/p>\n<h2>See also<\/h2>\n<div class=\"see-also-links output-inline\" id=\"see-also\">\n<ul><li><a href=\"\/development-resources\/logs-resources\/webhook-event-logs\/\"\n                        target=\"_self\"\n                        >\n                    Webhook event logs\n                <\/a><\/li><li><a href=\"\/development-resources\/webhooks\/handle-webhook-events\"\n                        target=\"_self\"\n                        >\n                    Handle webhook events\n                <\/a><\/li><li><a href=\"\/development-resources\/webhooks\/\"\n                        target=\"_self\"\n                        >\n                    Webhooks overview\n                <\/a><\/li><li><a href=\"\/development-resources\/webhooks\/secure-webhooks\/\"\n                        target=\"_self\"\n                        >\n                    Secure webhooks\n                <\/a><\/li><\/ul><\/div>\n","url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/troubleshoot","articleFields":{"description":"Find, diagnose, and resolve webhook delivery failures using the tools in your Customer Area.","feedback_component":true,"type":"page","operations":"","status":"current","filters_component":false,"page_id":"c37058ea-1d0f-4245-bae3-d9d554276a25","decision_tree":"[]"},"algolia":{"url":"https:\/\/docs.adyen.com\/development-resources\/webhooks\/troubleshoot","title":"Troubleshoot webhooks","content":"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.\nRetry queue\nIf 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 before placing the webhook into a retry queue. The initial delivery attempts are sent at 9 seconds, 18 seconds, and again at 27 seconds. Retry queues are separate for each webhook endpoint. If you have multiple endpoints, you must troubleshoot them individually.\nFrom 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:\n\n2 minutes\n5 minutes\n10 minutes\n15 minutes\n30 minutes\n1 hour\n2 hours\n4 hours\n8 hours\n\nIf a retry is successful, we continue with the next webhook in the queue.\nTroubleshoot failures\n\nIn your Customer Area, go to Developers &gt; Webhooks.\nFind the webhook endpoint with a Failing status and select it.\nSelect Troubleshoot to view the list of failed webhook messages for that endpoint. Each failed event includes an error message and a timestamp.\n\nThis video shows how to find and troubleshoot failing webhooks:\n\nThe 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:\n\n\n\nHTTP Error\nPotential Cause\nRecommended Action\n\n\n\n\n401: Unauthorized\nYour server is refusing the connection due to invalid credentials.\nCheck that your webhook security (basic authentication or HMAC) is set up correctly. Consider rotating credentials if they have been compromised.\n\n\n404: Not found\nThe webhook URL could not be reached.\nEnsure the endpoint URL is correct, publicly accessible, and not blocked by a firewall.\n\n\n422: Unprocessable content\nYour server received the webhook but your business logic rejected it.\nThis can be due to validation logic on your endpoint. We recommend acknowledging receipt with [200 OK] first, and performing business logic separately.\n\n\n429: Too many requests\nYour server is rate-limiting requests from Adyen.\nThis 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.\n\n\n500: Internal server error\nA generic error occurred on your server.\nCheck your server logs to identify the root cause. Ensure the endpoint is available and the application is running correctly.\n\n\n\n\nMultiple 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.\n\nResolve failures\nFrom the Troubleshoot page for a failing webhook, you can manually intervene:\n\nRetry: After you deploy a fix, manually send the webhook message to your server again.\nIgnore: If a webhook is no longer needed, permanently remove it from the queue.\n\nAfter you have identified the cause of the failure and deployed a fix to your server:\n\nNavigate to the failed webhook event as shown in Step 1.\nSelect 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.\nIf the webhook event is outdated or no longer relevant, select Ignore. The event is permanently removed from the queue and cannot be retried.\n\nSet up failure alerts\nYou can receive alerts by email or in the Customer Area notification center when webhooks fail. Adyen sends the following types of alerts:\n\nInitial 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.\nOngoing Failure: Get notified if a failing endpoint remains unresponsive for an extended period. Adyen sends an alert after 7 days of a webhook failing.\nRecovery: Adyen informs you when a previously failing webhook endpoint successfully starts accepting events again.\n\nTo configure alerts:\n\nIn your Customer Area, go to Notification center  &gt; Settings.\nUnder Developers and Integrations, find the topic Webhooks.\nUse the toggles to enable or disable Email or Notification center alerts.\n\nWhen the Email toggle is enabled, email notifications are sent to the email address linked to your user.\nSee also\n\n\n                    Webhook event logs\n                \n                    Handle webhook events\n                \n                    Webhooks overview\n                \n                    Secure webhooks\n                \n","type":"page","locale":"en","boost":17,"hierarchy":{"lvl0":"Home","lvl1":"Development resources","lvl2":"Webhooks","lvl3":"Troubleshoot webhooks"},"hierarchy_url":{"lvl0":"https:\/\/docs.adyen.com\/","lvl1":"https:\/\/docs.adyen.com\/development-resources","lvl2":"https:\/\/docs.adyen.com\/development-resources\/webhooks","lvl3":"\/development-resources\/webhooks\/troubleshoot"},"levels":4,"category":"Development Resources","category_color":"green","tags":["Troubleshoot","webhooks"]}}