Skip to content
PayloadPuffin.
Join the waitlist

Verify signatures

Anyone who learns your receiver's URL can POST to it. Every request PayloadPuffin sends is signed with the destination's signing secret, so your receiver can reject anything that wasn't.

Before you start

You need:

  • The destination's signing secret, which starts with whsec_. It is in the response that created the destination. To read it again, call Get a destination with include=secret and a key that has both destinations:read and destinations:write, or reveal it on the destination's page in the console as an owner or admin.
  • Access to the raw request body, as bytes. Many frameworks parse JSON before your handler runs; turn that off for this route, because re-serialized JSON doesn't match the signature.

How a request is signed

Each request carries three headers:

HeaderValue
webhook-idThe delivery ID, such as dlv_01jbsw8qbee008000000000008. Every attempt of one delivery, including a resend, sends the same ID
webhook-timestampWhen this attempt was signed, in seconds since the Unix epoch, such as 1791720000
webhook-signaturev1, followed by the base64 signature. During a secret rotation, two of these separated by a space

PayloadPuffin computes the signature as follows:

  1. Join webhook-id, webhook-timestamp and the request body with periods: {webhook-id}.{webhook-timestamp}.{body}. The body is the exact bytes you received, after any transform.
  2. Compute an HMAC-SHA256 over those bytes. The key is the part of the secret after whsec_, base64-decoded.
  3. Encode the result as base64 and prefix it with v1,.

This is the Standard Webhooks scheme, so its libraries verify these requests. With the standardwebhooks package for Node.js, new Webhook(secret).verify(rawBody, headers) throws unless the request is valid and signed within five minutes.

Verify a request

This function returns true only for a request signed with your secret in the last five minutes. It is the same check the library makes, written out:

verify-signature.ts
import { createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 5 * 60;

export function verifyWebhook(
	secret: string,
	headers: Headers,
	body: Uint8Array,
	now: number = Date.now(),
): boolean {
	const id = headers.get('webhook-id');
	const timestamp = headers.get('webhook-timestamp');
	const signatures = headers.get('webhook-signature');
	if (id === null || timestamp === null || signatures === null) return false;
	if (!/^\d+$/.test(timestamp) || Math.abs(now / 1000 - Number(timestamp)) > TOLERANCE_SECONDS) return false;

	const key = Buffer.from(secret.replace(/^whsec_/, ''), 'base64');
	const expected = createHmac('sha256', key).update(`${id}.${timestamp}.`).update(body).digest();

	return signatures.split(' ').some((entry) => {
		const [version, encoded] = entry.split(',');
		if (version !== 'v1' || encoded === undefined) return false;
		const received = Buffer.from(encoded, 'base64');
		return received.length === expected.length && timingSafeEqual(received, expected);
	});
}

It does four things:

  1. It reads the three headers and refuses a request that lacks one.
  2. It refuses a timestamp more than five minutes from your clock. That limits how long a captured request can be replayed. Pick another window if you need one; every attempt, including every retry, is signed at the moment it is sent.
  3. It computes the expected signature over the raw body bytes.
  4. It compares the expected signature with every v1 entry in constant time and accepts the request if any entry matches.

Call it before you parse the body. This minimal Node.js receiver verifies requests with JSON bodies, then parses the JSON:

receive-webhook.ts
import { createServer } from 'node:http';
import { verifyWebhook } from './verify-signature.ts';

const secret = process.env.PAYLOADPUFFIN_SIGNING_SECRET;
if (secret === undefined)
	throw new Error('Set PAYLOADPUFFIN_SIGNING_SECRET to the destination signing secret.');
const port = Number(process.env.PORT ?? 3000);

createServer(async (request, response) => {
	const chunks: Buffer[] = [];
	for await (const chunk of request) chunks.push(chunk as Buffer);
	const body = Buffer.concat(chunks);

	const headers = new Headers();
	for (const [name, value] of Object.entries(request.headers)) {
		if (typeof value === 'string') headers.set(name, value);
	}

	if (!verifyWebhook(secret, headers, body)) {
		response.writeHead(401).end();
		return;
	}

	const payload: unknown = JSON.parse(body.toString('utf8'));
	console.log(headers.get('webhook-id'), payload);
	response.writeHead(204).end();
}).listen(port);

Save both files, then start the receiver with Node.js 24 or later, which runs TypeScript directly:

Shell
PAYLOADPUFFIN_SIGNING_SECRET=whsec_... node receive-webhook.ts

Answer the request

Return a 2xx status once you've verified and stored the event. Any other answer, including the 401 above, fails the attempt. See Retries for which failures are retried.

A delivery can arrive more than once. A retry after a timeout, or a resend, sends it again with the same webhook-id. Record the IDs you've processed and skip a repeat. One event produces at most one delivery per destination, so a repeated webhook-id is always the same delivery sent again.

Rotate the secret

Rotate the secret when it may have leaked, or on a schedule. Rotation keeps the old secret signing for a grace period, so you can deploy the new one without dropping requests.

  1. Call Rotate a destination signing secret with expiry set to how long the old secret should keep signing: immediately, 1h, 2h, 4h, 8h, 12h, 24h, 3d or 7d. The response carries the new secret.
  2. Until that expiry, each request carries two signatures, the new secret's first. The function above accepts either, so a receiver with the old secret keeps working.
  3. Deploy the new secret to your receiver.
  4. Call Expire the previous signing secret to stop signing with the old secret now, or let the expiry pass.

Both calls need the destinations:write scope. A second rotation is refused with 409 while the old secret is still signing; expire it first. With immediately, the old secret stops signing at once, so requests in between fail verification until your receiver has the new secret.