Adyen webhooks in production: duplicates, ordering, retries and timeouts

Published · Updated

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

ProblemWhat to doWith Event Gateway
TimeoutsReturn a 2xx within 10 seconds; process in a background jobAccepts the delivery at once, then queues it for your service
DuplicatesKey on eventCode and pspReference; use the latest delivery's detailsDrops repeats on the fields you choose
OrderingCheck eventDate, and sequenceNumber where a webhook has itLogs every event and attempt, so you can see arrival order when debugging
RetriesTurn on alerts; retry from Troubleshoot; expect a burst after a fixAccepts deliveries while your service is down and replays them at a rate you set
Choosing eventsAccept every type with a 2xx; read success; enable the non-default codes you needFilters and routes events by type
TestingUse Test configuration, then a test paymentForwards to localhost and replays past events
Other limitsPlan for ports, inactive configurations, relayed webhooks and one type per endpointFans 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:

  1. Verify the HMAC signature.
  2. Store the message in a database or a queue.
  3. Return the status straight away, before any business logic. See why to process webhooks asynchronously.
  4. 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:

  1. Build the key from eventCode and pspReference, with a unique constraint in your database.
  2. When a key repeats, update your record from the newer delivery rather than discarding it, as Adyen tells you to use the latest details.
  3. 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:

  1. Compare eventDate on Payments webhooks, or timestamp on Platforms webhooks, before you overwrite newer state with an older event.
  2. Use sequenceNumber where it's present. On transfer webhooks it counts the webhooks sent for that transfer, so a gap shows you're missing one.
  3. Link related events by reference: modifications carry the original payment's pspReference in originalReference.
  4. 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:

  1. 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.
  2. Diagnose from Developers > Webhooks: select the Failing webhook, then Troubleshoot, which lists each failed message with its error.
  3. After you deploy a fix, select Retry on the failed message, or Ignore to remove it permanently.
  4. 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:

  1. Return early for event codes you don't handle, after accepting them.
  2. Read success as well as eventCode. Most codes report the result of a request, so an AUTHORISATION with success set to false doesn't mean a payment went through. The value is a string in the JSON examples.
  3. Handle CAPTURE_FAILED and REFUND_FAILED as well. They report a rejection by the card scheme, separately from the result in CAPTURE or REFUND.
  4. 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:

  1. 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.
  2. Create a test payment and match the webhook to it by pspReference or merchantReference, as Adyen recommends for end-to-end testing.
  3. Keep payload fixtures for edge cases; Adyen webhook events has samples to start from.
  4. 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.

Not affiliated with Adyen. Facts are compiled from public sources and linked inline.