Skip to content
HookDeploy

Adyen webhooks

Last verified against Adyen's documentation on September 27, 2026.

On this page ↓

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

AreaExample event codesTypical use
PaymentsAUTHORISATION, CAPTURE, CAPTURE_FAILED, CANCELLATIONFulfill orders and track captures
RefundsREFUND, REFUND_FAILEDRecord refunds
DisputesCHARGEBACK, NOTIFICATION_OF_CHARGEBACK, CHARGEBACK_REVERSEDRespond to disputes
TokensRECURRING_CONTRACTStore payment details for recurring payments
ReportsREPORT_AVAILABLEDownload 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

BehaviorDetail
Method and formatPOST 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
AuthenticationOptional Basic Auth username and password, set in the Customer Area
AcceptingAny 2xx within 10 seconds. Older integrations answered with an [accepted] body, which is no longer required
Failing stateAn endpoint that doesn’t accept in time goes into a failing state, and new events for it are queued
RetriesAt 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 retryFrom the Customer Area’s troubleshooting tools
DeduplicationpspReference 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, and success, 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 Authorization header 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

  1. In HookDeploy, create an endpoint (for example, Adyen live) and copy its URL.
  2. 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.
  3. 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.
  4. 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.

Capture Adyen webhooks free

Start free