This page describes how to receive and process Adyen webhooks correctly so your system stays in sync with payment events.
The order of operations
When your endpoint receives a webhook, handle it in this order:
Verify that the webhook is genuinely from Adyen. See Security (HMAC Validation).
Store the message in your database or a queue so you can process it later.
Acknowledge the webhook by responding with a successful HTTP status code, such as 200 or 202. Do not validate or process the data at this step. If Adyen does not receive a 2xx response within 10 seconds, the event is marked as failing and placed in a retry queue.
Process the data and apply your business logic, only after you have acknowledged the webhook. Errors in your business logic can otherwise cause failing webhooks.
Acknowledge first, then process asynchronously. Keep the response fast and do the heavier work afterward.
Acknowledging the webhook
Respond quickly with a 2xx status to confirm delivery.
on POST /webhooks:
if not verifyHmac(notification): return 401 // reject unauthentic messages
store(notification) // persist before processing
respond 200 // acknowledge within 10 seconds
enqueue(notification) // process asynchronously after acknowledging
Handle events idempotently
You may receive the same webhook more than once. Duplicate events share the same eventCode and pspReference, while eventDate and other fields may differ. Use these fields to recognize duplicates and avoid applying the same change twice, for example by recording which pspReference plus eventCode combinations you have already processed. When you do receive a duplicate, use the details from the latest event.
Expect out-of-order and retried events
Webhooks may arrive out of order or be retried after a failure. To process events in the correct chronological order, check the eventDate timestamp, and use any sequence identifiers present. Do not assume the order of arrival reflects the order of the events.
Update your order from the webhook
Use the webhook as the authoritative source for updating your order or backend state. Match each webhook to the corresponding transaction using pspReference or your own merchantReference, then update the order based on the eventCode and success fields. For example, an AUTHORISATION with success: true can mark the order as paid. Rely on the webhook rather than the synchronous API or frontend result alone.
Adyen's server libraries can deserialize, verify, and parse webhook payloads, which reduces boilerplate.
When webhooks are missing or failing
If expected webhooks do not arrive or are failing, see Troubleshooting Failed Webhooks in Adyen and Missing CAPTURE Webhooks. Note that the CAPTURE webhook is not sent for automatic captures by default. See Event Types.