Adyen webhooks in production: duplicates, ordering, retries and timeouts
This guide covers the problems Adyen webhooks cause in production and how to handle each one. What Adyen sends and how it's signed is on the Adyen webhooks overview, every event type is on Adyen webhook events, and signature verification code is on Verify Adyen webhooks.
At a glance
| Problem | What to do | With Event Gateway |
|---|---|---|
| Timeouts | Return a 2xx within 10 seconds; process in a background job | Accepts the delivery at once, then queues it for your service |
| Duplicates | Key on eventCode and pspReference; use the latest delivery's details | Drops repeats on the fields you choose |
| Ordering | Check eventDate, and sequenceNumber where a webhook has it | Logs every event and attempt, so you can see arrival order when debugging |
| Retries | Turn on alerts; retry from Troubleshoot; expect a burst after a fix | Accepts deliveries while your service is down and replays them at a rate you set |
| Choosing events | Accept every type with a 2xx; read success; enable the non-default codes you need | Filters and routes events by type |
| Testing | Use Test configuration, then a test payment | Forwards to localhost and replays past events |
| Other limits | Plan for ports, inactive configurations, relayed webhooks and one type per endpoint | Fans one endpoint out to many destinations |
Adyen webhook timeouts and what to respond with
Return a 2xx status within 10 seconds, then do the work in a background job. For Standard webhooks the status is all Adyen reads, so no response body is needed.
Why it happens: Adyen wants each message acknowledged before you run your business logic. If it doesn't get a successful status within 10 seconds, for example because your server is down, it marks the webhook as Failing and all events to that endpoint go to the retry queue. An error status from your own validation counts as a failure too, which is why Adyen says not to validate or process the data at this step.
What to respond with: It depends on the product.
- Standard webhooks, and most Balance Platform and Management webhooks: any 2xx, such as 200 or 202.
- Terminal assignment completed, terminal settings modified and terminal boarding triggered: 200 only.
- Classic Adyen for Platforms notifications: the literal body
[accepted]. Adyen retries until it gets it. The two Balance Platform Accounting notification specs also ask for it. - Relayed authorisation and relayed authentication: a 200 with your decision in the body, within two seconds. See other limits.
An HTTP 200 with the body [accepted] satisfies everything except the two relayed webhooks, so it's a safe default for a handler that receives several types.
Fix it in your handler:
- Verify the HMAC signature.
- Store the message in a database or a queue.
- Return the status straight away, before any business logic. See why to process webhooks asynchronously.
- Process the stored message in a background worker.
app.post("/webhooks/adyen", express.json(), async (req, res) => {
// Verify the HMAC on the item first (see the Verify page), then:
await processQueue.add(req.body);
res.status(200).send("[accepted]");
});
With Event Gateway: Hookdeck answers each Adyen delivery immediately with an HTTP 200 and [accepted], then queues events and delivers them to your service at a rate it can handle, with its own retries. Your handler can take as long as it needs without failing an Adyen delivery. See how to solve Adyen webhook timeout errors.
Duplicate Adyen webhooks
Adyen can send the same event twice. Key on eventCode and pspReference, and use the details from the latest delivery.
Why it happens: Adyen retries any delivery it doesn't see accepted, so a message you processed can come back if your acknowledgement was lost or late. The two copies have the same eventCode and pspReference, but eventDate and other fields can differ, so comparing whole payloads won't catch them.
Fix it in your handler:
- Build the key from
eventCodeandpspReference, with a unique constraint in your database. - When a key repeats, update your record from the newer delivery rather than discarding it, as Adyen tells you to use the latest details.
- Make every side effect idempotent, so shipping an order or issuing a refund happens once however many times the event arrives.
With Event Gateway: Hookdeck deduplicates events on the payload fields you choose, so you can filter repeats before they reach your endpoint.
Ordering Adyen webhooks
Check the timestamp. Adyen's docs tell you to do this to process events in chronological order, and some webhooks also give you a sequenceNumber.
Why it happens: Adyen uses at-least-once delivery, and failed deliveries wait in a retry queue that can run for days. A message can reach you long after the event it describes. For more on the general problem, see Webhook Ordering: Why It's Hard and How to Handle It.
Fix it in your handler:
- Compare
eventDateon Payments webhooks, ortimestampon Platforms webhooks, before you overwrite newer state with an older event. - Use
sequenceNumberwhere it's present. On transfer webhooks it counts the webhooks sent for that transfer, so a gap shows you're missing one. - Link related events by reference: modifications carry the original payment's
pspReferenceinoriginalReference. - Write state transitions that tolerate events in any order.
With Event Gateway: Hookdeck logs every event and delivery attempt, so when state looks wrong you can see the order events actually arrived in and replay them.
Adyen webhook retries and the retry queue
Adyen retries a failed delivery a few more times, then queues it for up to 30 days. Turn on alerts so a failing endpoint doesn't go unnoticed.
Why it happens: After the first failures, Adyen sets the webhook's status to Failing and moves it to the retry queue. From there it retries at intervals of 30 seconds, 30 seconds, 1 minute, 2, 5, 10, 15 and 30 minutes, then 1, 2, 4 and 8 hours, for up to 30 days. Adyen's docs don't say what happens to an event when that time runs out. A success on one webhook type doesn't tell you the others are healthy.
Fix it in your handler:
- Turn on alerts in your Customer Area under Notification center > Settings, in the Webhooks topic. Adyen alerts you after 5 retry attempts, again after 7 days of failing, and when the endpoint recovers.
- Diagnose from Developers > Webhooks: select the Failing webhook, then Troubleshoot, which lists each failed message with its error.
- After you deploy a fix, select Retry on the failed message, or Ignore to remove it permanently.
- Size your server for the backlog. Queued webhooks arrive in a short time once the endpoint recovers, and your own rate limits can answer them with a 429.
With Event Gateway: Hookdeck captures every Adyen delivery while your services are down, so Adyen's deliveries succeed and the webhook doesn't go to Failing. Failed events can be retried automatically, manually or in bulk once you recover, at a rate you set, so a backlog doesn't arrive all at once.
Choosing which Adyen events to listen to
Standard webhooks include default event codes that can't be turned off, so accept every type with a 2xx and ignore the ones you don't use. Enable the non-default codes you need.
Why it matters: Adyen says to expect new event types, and an error status for an unknown one would fail the delivery. Some useful codes are off by default: REFUND_NOT_CLEARED and SETTLED_REVERSED are on the Standard webhook page, CAPTURE for delayed automatic capture needs enabling on both the Standard webhook page and the Webhooks settings page, and MANUAL_REVIEW_ACCEPT and MANUAL_REVIEW_REJECT are in Risk settings. Adyen doesn't send a webhook when a payment settles successfully. The full list, with sample payloads, is on Adyen webhook events.
Fix it in your handler:
- Return early for event codes you don't handle, after accepting them.
- Read
successas well aseventCode. Most codes report the result of a request, so anAUTHORISATIONwithsuccessset tofalsedoesn't mean a payment went through. The value is a string in the JSON examples. - Handle
CAPTURE_FAILEDandREFUND_FAILEDas well. They report a rejection by the card scheme, separately from the result inCAPTUREorREFUND. - Configure webhooks on the company account, as Adyen recommends, and include or exclude merchant accounts there. Platforms webhooks can only be configured at that level.
With Event Gateway: Hookdeck filters and routes events by eventCode or any other property, so your handler only sees the events it processes.
Testing and debugging Adyen webhooks locally
Test the connection from your Customer Area, then make a test payment and watch the webhooks it produces.
Why it happens: Adyen needs a public URL with no redirects, and development machines sit behind NAT and firewalls. Live webhooks also have to be set up separately, because Adyen has no way to copy a configuration from test to live.
How to test:
- In your Customer Area, go to Developers > Webhooks, edit the webhook and select Test configuration. Pick an event type and read any error it returns.
- Create a test payment and match the webhook to it by
pspReferenceormerchantReference, as Adyen recommends for end-to-end testing. - Keep payload fixtures for edge cases; Adyen webhook events has samples to start from.
- Before going live, recreate each webhook in the live Customer Area and switch to the live HMAC key, which is different from the test one.
With Event Gateway: The Hookdeck CLI receives webhooks on your machine with hookdeck listen 3000 adyen, on a URL that doesn't change when the tunnel restarts, and you can replay past events. See how to test and replay Adyen webhooks locally.
Other Adyen webhook limits
Plan for Adyen's port rules, configuration clean-up, relayed webhooks and one-type-per-endpoint rule before they reach production.
Allowed ports and TLS. Live endpoints must use HTTPS with TLS 1.2 or 1.3 on port 443, 8443 or 8843. Test endpoints can also use HTTP on port 80, 8080 or 8888. The URL must be public, with no redirects.
Inactive configurations are deleted. Adyen automatically deletes webhook configurations that have been inactive for more than six months. It doesn't define inactive further. The rule sits in its section on disabling webhooks, which also says events queue while a webhook is disabled and arrive when you enable it again. Enable or remove disabled configurations rather than leaving them.
Relayed webhooks need your answer in the response. balancePlatform.authorisation.relayed and balancePlatform.authentication.relayed expect an HTTP 200 with your decision in the body within two seconds. If it doesn't arrive, Adyen applies your fallback logic for an authorisation, and the process stops for an authentication. Don't acknowledge these and process them later.
One webhook type per endpoint. Each endpoint receives one type of webhook, and each webhook delivers to one URL. Getting the same events into several systems means building a fan-out. Adyen also recommends limiting the number of webhooks on each company account.
No IP list to allow. Adyen doesn't publish IP addresses. Allow the domain out.adyen.com, or resolve it regularly; Adyen recommends checking every hour.
SOAP batches. JSON and HTTP POST deliveries contain one notification item, while SOAP deliveries can contain up to six. Loop over notificationItems whichever you use.
With Event Gateway: Hookdeck sends one Adyen endpoint's events to as many destinations as you need, and can deliver to any port on your infrastructure.
Keep a slow handler from sending every Adyen event to the retry queue.
Hookdeck Event Gateway accepts each Adyen delivery at once, verifies its signature, queues events and retries to your service on your schedule.