Verify Adyen webhooks

Verify that a webhook really came from Adyen (Europe) before acting on it.

Identifier	'adyen'
Import	import { verifyAdyen } from 'verihook/adyen'
Headers	hmacsignature (platform and management webhooks)
Signature	Standard webhooks: base64 HMAC-SHA256 of selected fields of each notification item, in additionalData.hmacSignature. Platform and management webhooks: base64 HMAC-SHA256 of the raw body in the HmacSignature header.
Replay window	None (the provider sends no timestamp)
result.eventType	the first item’s eventCode, e.g. AUTHORISATION

Get your secret

The webhook’s HMAC key (hex): in the Customer Area, open Developers → Webhooks, edit the webhook and generate the HMAC key under its security settings.

Store it in an environment variable (ADYEN_HMAC_KEY below) and never commit it.

Verify a request

import { verifyAdyen } from 'verihook/adyen';

export async function POST(request: Request) {
  const result = await verifyAdyen(request, process.env.ADYEN_HMAC_KEY!);

  if (!result.valid) {
    console.warn(result.code, result.reason, result.hint);
    return new Response('Invalid signature', { status: 401 });
  }

  console.log(result.eventType, result.event);
  return Response.json({ received: true });
}

request can be a Fetch Request or { headers, body, url? } with the raw body. verifyWebhook('adyen', request, secret) from verihook does the same. Read why the raw body matters if verification fails behind a body parser.

Framework examples

Next.js

app/api/webhooks/adyen/route.ts

import { createWebhookHandler } from 'verihook/next';

export const POST = createWebhookHandler('adyen', process.env.ADYEN_HMAC_KEY!, async (payload, result) => {
  // Runs only for a valid signature
  console.log(result.eventType, result.event);
});

Express

import express from 'express';
import { verihookExpress, type VerihookRequestAdditions } from 'verihook/express';

const app = express();

// Register before express.json(), or keep express.json() off this route
app.post('/webhooks/adyen', verihookExpress('adyen', process.env.ADYEN_HMAC_KEY!), (req, res) => {
  const { eventType, event } = (req as typeof req & VerihookRequestAdditions).verihook!;
  res.json({ received: true });
});

Fastify

import Fastify from 'fastify';
import { verihookFastify, verihookRawBody, type VerihookFastifyRequest } from 'verihook/fastify';

const app = Fastify();
await app.register(verihookRawBody);

app.post('/webhooks/adyen', { preHandler: verihookFastify('adyen', process.env.ADYEN_HMAC_KEY!) }, async (request) => {
  const { eventType, event } = (request as typeof request & VerihookFastifyRequest).verihook!;
  return { received: true };
});

Hono

import { Hono } from 'hono';
import { verihookHono, type VerihookVariables } from 'verihook/hono';

const app = new Hono<{ Bindings: { ADYEN_HMAC_KEY: string }; Variables: VerihookVariables }>();

app.post('/webhooks/adyen', verihookHono('adyen', (c) => c.env.ADYEN_HMAC_KEY), (c) => {
  const { eventType, event } = c.get('verihook');
  return c.json({ received: true });
});

NestJS

// main.ts: NestFactory.create(AppModule, { rawBody: true })
import { Controller, Post, Req, UseGuards } from '@nestjs/common';
import { createVerihookGuard, type VerihookNestRequest } from 'verihook/nestjs';

@Controller('webhooks')
export class WebhooksController {
  @Post('adyen')
  @UseGuards(createVerihookGuard('adyen', process.env.ADYEN_HMAC_KEY!))
  handle(@Req() req: VerihookNestRequest) {
    const { eventType, event } = req.verihook!;
  }
}

Nuxt / h3

server/api/webhooks/adyen.post.ts

import { createWebhookHandler } from 'verihook/h3';

export default defineEventHandler(
  createWebhookHandler('adyen', process.env.ADYEN_HMAC_KEY!, async (payload, result) => {
    console.log(result.eventType);
  }),
);

SvelteKit

src/routes/webhooks/adyen/+server.ts

import { env } from '$env/dynamic/private';
import { createWebhookHandler } from 'verihook/sveltekit';

export const POST = createWebhookHandler('adyen', () => env.ADYEN_HMAC_KEY, async (payload, result) => {
  console.log(result.eventType);
});

Remix / React Router

app/routes/webhooks.adyen.ts

import { createWebhookHandler } from 'verihook/remix';

export const action = createWebhookHandler('adyen', process.env.ADYEN_HMAC_KEY!, async (payload, result) => {
  console.log(result.eventType);
});

Astro

src/pages/api/webhooks/adyen.ts

import { createWebhookHandler } from 'verihook/astro';

export const prerender = false;
export const POST = createWebhookHandler('adyen', import.meta.env.ADYEN_HMAC_KEY, async (payload, result) => {
  console.log(result.eventType);
});

AWS Lambda

import { createWebhookHandler } from 'verihook/lambda';

export const handler = createWebhookHandler('adyen', process.env.ADYEN_HMAC_KEY!, async (payload, result) => {
  console.log(result.eventType);
});

Each adapter responds 401 to an invalid signature, 413 to a body over maxBodySize (2 MB by default) and 200 to a duplicate when you pass a dedupeStore.

Things to know

• Every item in a batch must verify, or the whole request is rejected.
• Adyen expects [accepted] as the response body for standard webhooks.

Testing

signWebhook from verihook/testing builds a correctly signed Adyen request for your tests:

import { signWebhook } from 'verihook/testing';
import { verifyAdyen } from 'verihook/adyen';

const hook = await signWebhook('adyen', {
  secret: '0123456789abcdef0123456789abcdef',
  payload: { id: 'evt_test' },
});

const result = await verifyAdyen(
  { headers: hook.headers, body: hook.body, url: hook.url },
  hook.secret,
);
// result.valid === true

From the command line, npx verihook simulate adyen --url http://localhost:3000/webhooks/adyen sends one to your local server.

See Testing your handlers for supertest and Fetch Request examples.

Troubleshooting

Failed results carry a code and often a hint with the likely cause. See Troubleshooting for each error code.

Adyen’s webhook documentation