Skip to content

Verifying signatures

Every delivery is signed with the subscription’s secret (whsec_…, shown once when you create the subscription or rotate it). Check the signature on every request before you act on it; a receiver that doesn’t is open to anyone who finds its URL.

Runbook-Timestamp: 1763458212
Runbook-Signature: v1=b528e12e66278e5153b4c540e627aecbb327bbeefab40ff5f439b078ca22b2f2
  1. Take the Runbook-Timestamp header (Unix seconds) and the raw request body, byte for byte, before any JSON parsing.
  2. Compute HMAC-SHA256 of "{timestamp}.{body}", keyed by the secret string itself (all of it, whsec_ included), as lowercase hex.
  3. Runbook-Signature holds one or more v1=<hex> entries, comma-separated. Accept the request if any entry equals your result, compared in constant time. During a secret rotation the header carries one entry per active secret, newest first, for 24 hours.
  4. Reject timestamps more than 5 minutes from your clock, so a captured request can’t be replayed later.

Then deduplicate on the event ID (Runbook-Event-Id, the body’s id): delivery is at least once, so the same event can arrive more than once.

Each function takes the secret, the raw body, the two headers and the current time, and returns whether the delivery is authentic.

verify.ts
import { createHmac, timingSafeEqual } from 'node:crypto';
const TOLERANCE_SECONDS = 300;
export function verifyRunbookSignature(
secret: string, // the subscription's whsec_… secret
rawBody: string | Buffer, // the request body exactly as received
timestamp: string, // the Runbook-Timestamp header
signatureHeader: string, // the Runbook-Signature header
nowSeconds: number = Math.floor(Date.now() / 1000),
): boolean {
if (!/^[0-9]+$/.test(timestamp)) return false;
if (Math.abs(nowSeconds - Number(timestamp)) > TOLERANCE_SECONDS) return false;
const expected = Buffer.from(
createHmac('sha256', secret).update(`${timestamp}.`).update(rawBody).digest('hex'),
);
return signatureHeader.split(',').some((entry) => {
const value = entry.trim();
if (!value.startsWith('v1=')) return false;
const candidate = Buffer.from(value.slice(3));
return candidate.length === expected.length && timingSafeEqual(candidate, expected);
});
}

With Express, read the body raw for this route:

server.ts
import express from 'express';
import { verifyRunbookSignature } from './verify.ts';
const app = express();
app.post('/runbook', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyRunbookSignature(
process.env.RUNBOOK_WEBHOOK_SECRET!,
req.body,
req.get('Runbook-Timestamp') ?? '',
req.get('Runbook-Signature') ?? '',
);
if (!ok) return res.status(401).end();
const event = JSON.parse(req.body.toString('utf8'));
// Deduplicate on event.id, then hand the work off and answer quickly.
res.status(204).end();
});
app.listen(9000);

Check your implementation against this delivery, with the clock at the timestamp:

Secret whsec_RTvjUcKXtNZ1T5WVpsbUlo3e0xgR8z8ApXzhxQ8Ke2w
Runbook-Timestamp 1763458212
Body {"id":"evt_01JD2W1B3D5F7H9K1M3P5R7T9V","type":"webhook.test","version":1}
Runbook-Signature v1=b528e12e66278e5153b4c540e627aecbb327bbeefab40ff5f439b078ca22b2f2

The same body with any byte changed, or a timestamp more than 300 seconds away, must fail. (The site’s tests run all three samples against this vector.)

Terminal window
runbook webhook rotate-secret whk_… --project prod --json

The new secret is printed once. For the next 24 hours, deliveries are signed with both the new and the previous secret, so switch your receiver to the new one within that window. A receiver may hold both secrets while it switches: accept a match on either.