Adyen webhooks
Last verified against Adyen's documentation on September 27, 2026.
Adyen sends webhooks for what happens to payments and your account: authorisations, captures, refunds, chargebacks, and payouts. Adyen is strict about timing. If your endpoint doesn’t accept a webhook within 10 seconds, Adyen puts the endpoint in a failing state and queues every new event for it, not just the one that failed. Its HMAC signature is also unusual: for payment webhooks it covers a set of fields, not the raw body. This page covers what Adyen sends, how it delivers, how to fix the common errors, and where HookDeploy fits.
What Adyen sends webhooks for
| Area | Example event codes | Typical use |
|---|---|---|
| Payments | AUTHORISATION, CAPTURE, CAPTURE_FAILED, CANCELLATION | Fulfill orders and track captures |
| Refunds | REFUND, REFUND_FAILED | Record refunds |
| Disputes | CHARGEBACK, NOTIFICATION_OF_CHARGEBACK, CHARGEBACK_REVERSED | Respond to disputes |
| Tokens | RECURRING_CONTRACT | Store payment details for recurring payments |
| Reports | REPORT_AVAILABLE | Download settlement reports |
Standard payment webhooks are a JSON POST with a notificationItems array. Each NotificationRequestItem has an eventCode, a success flag, a pspReference, the merchantReference, an amount, and additionalData, which carries the hmacSignature.
How Adyen delivers webhooks
| Behavior | Detail |
|---|---|
| Method and format | POST with a JSON body |
| Signature (payment webhooks) | additionalData.hmacSignature on each item: a base64 HMAC-SHA256 over specific fields joined with colons, keyed with your hex-decoded HMAC key |
| Signature (other webhooks) | An hmacSignature header over the whole raw body |
| Authentication | Optional Basic Auth username and password, set in the Customer Area |
| Accepting | Any 2xx within 10 seconds. Older integrations answered with an [accepted] body, which is no longer required |
| Failing state | An endpoint that doesn’t accept in time goes into a failing state, and new events for it are queued |
| Retries | At 2, 5, 10, 15, and 30 minutes, then 1, 2, and 4 hours, then regularly for up to 7 days, then every 8 hours for the following 7 days |
| Manual retry | From the Customer Area’s troubleshooting tools |
| Deduplication | pspReference together with eventCode |
Common Adyen webhook errors and how to fix them
Every event is delayed
A single slow response puts your endpoint in a failing state, and Adyen queues all new events until it accepts again. Accept within 10 seconds, store the event, and process it afterward.
HMAC validation fails
- Wrong input. For payment webhooks, the signature covers
pspReference,originalReference,merchantAccountCode,merchantReference,amount.value,amount.currency,eventCode, andsuccess, joined with colons, not the raw body. Use Adyen’s library. - Key not decoded. The HMAC key from the Customer Area is hex. Decode it before use.
- Wrong key. Each webhook has its own HMAC key. Keep the old key during rotation until events signed with it have drained.
Basic Auth failing
Adyen sends the credentials you configured in the Authorization header. If a proxy sits in front of your handler, make sure it passes the header through.
Duplicate events
Retries resend the same notification. Deduplicate on pspReference and eventCode.
Why use HookDeploy with Adyen
Never go into a failing state
HookDeploy captures every Adyen webhook at Cloudflare’s edge and responds right away, before forwarding it to your server. Adyen gets its 2xx in milliseconds, so your endpoint never goes into a failing state, and one slow deploy can’t queue every event behind it.
- Destination retries. Starter retries 3 times (after 30 seconds, 5 minutes, and 30 minutes). Pro and Scale retry up to 5 times on a schedule you choose. Free doesn’t retry automatically.
- Incidents. Forward failures are grouped into incidents, and you can bulk-replay them once your server recovers.
- History. HookDeploy keeps captured webhooks for your plan’s retention period, from 7 days on Free to 365 days on Enterprise.
One webhook, many systems
Send each Adyen event to your app, your accounting or ERP system, and an alert channel in parallel. A failing destination doesn’t hold up the others. Free includes 1 destination per endpoint, Starter includes 5, and Pro and above are unlimited.
Deliver to systems Adyen can’t reach
The HookDeploy Agent connects outward from your network over mTLS and delivers events to a local port, so a billing or fulfillment service in a private network can receive Adyen events with no public endpoint.
Develop against real events
A tap sends a temporary copy of live Adyen events to 127.0.0.1 on your machine while production keeps receiving them.
Know the limits
- Basic Auth and retries. HookDeploy redacts the
Authorizationheader from stored requests, so retries and replays don’t carry Adyen’s Basic Auth credentials. Authenticate HookDeploy’s deliveries with a header you inject on the destination. - Plan limits. On Free, requests beyond the monthly allowance or the daily limit get a
429, which Adyen treats as a failed delivery. Paid plans keep accepting traffic past the included volume.
Signatures and authentication through HookDeploy
For payment webhooks, Adyen’s HMAC covers fields inside the body, and HookDeploy forwards the body unchanged, so retries and replays verify like the original delivery. For webhooks signed with the hmacSignature header, the header and body are forwarded unchanged too. A transformation, or a privacy filter that changes the stored copy used for retries and replays, breaks the signature at that destination.
Don’t authenticate HookDeploy’s deliveries with Adyen’s Basic Auth credentials. HookDeploy redacts the Authorization header from stored requests, so retries and replays wouldn’t carry them. Inject your own Authorization header on the destination and check that instead. HookDeploy adds it to every forward, every retry, incident replays, and manual replays you send to that destination.
Set up Adyen with HookDeploy
- In HookDeploy, create an endpoint (for example,
Adyen live) and copy its URL. - On the Forwarding tab, add a destination pointing to your handler, or to an agent for private delivery. Add a header
Authorization: Bearer YOUR_HANDLER_SECRET, and set the destination’s retries. - In the Adyen Customer Area, go to Developers, then Webhooks, and add a Standard webhook with your HookDeploy URL. Generate an HMAC key and copy it.
- Use Test configuration on the webhook, and confirm the event appears in HookDeploy and reaches your handler.
Example handler (Node.js and Express)
import crypto from 'node:crypto';
import express from 'express';
import { hmacValidator } from '@adyen/api-library';
const app = express();
const validator = new hmacValidator();
const expectedAuth = Buffer.from(`Bearer ${process.env.HANDLER_SECRET}`);
app.post('/webhooks/adyen', express.json(), async (req, res) => {
// Check the header HookDeploy injects on every forward, retry, and destination replay.
const received = Buffer.from(req.get('authorization') ?? '');
if (received.length !== expectedAuth.length || !crypto.timingSafeEqual(received, expectedAuth)) {
return res.status(401).send('Unauthorized');
}
const items = (req.body.notificationItems ?? []).map((i) => i.NotificationRequestItem);
if (!items.every((item) => validator.validateHMAC(item, process.env.ADYEN_HMAC_KEY))) {
return res.status(401).send('Invalid HMAC');
}
res.sendStatus(202);
for (const item of items) {
await enqueue({ pspReference: item.pspReference, eventCode: item.eventCode, success: item.success, item });
}
// Deduplicate on pspReference plus eventCode in your worker.
});
FAQ
How do I validate an Adyen HMAC signature?
For standard payment webhooks, Adyen signs specific fields of each NotificationRequestItem joined with colons, using your hex-decoded HMAC key, and puts the base64 result in additionalData.hmacSignature. Use Adyen's library to validate it rather than building the string yourself.
Do I still need to respond with [accepted]?
No. Adyen now accepts any 2xx status code within 10 seconds, and a response body isn't required. Older integrations responded with an [accepted] body.
Why are all my Adyen webhooks delayed?
If your endpoint doesn't accept a webhook within 10 seconds, Adyen puts it in a failing state and queues every new event for that endpoint until it recovers. Respond fast and process asynchronously.
How long does Adyen retry webhooks?
Adyen retries at increasing intervals, from 2 minutes up to 4 hours, regularly for up to 7 days, and then every 8 hours for the following 7 days.
How do I deduplicate Adyen webhooks?
Use the pspReference together with the eventCode, since one payment produces several events.
Does HookDeploy break Adyen HMAC validation?
No. The HMAC for payment webhooks covers fields inside the body, and HookDeploy forwards the body unchanged, so first deliveries, retries, and replays all validate. Use an injected header, not Adyen's Basic Auth, to authenticate HookDeploy's deliveries.