Skip to content

Verify signatures

Every webhook request is signed with your subscription’s signing secret (whsec_..., shown once when you create the subscription or rotate the secret). Verify every request before you trust it.

signed_payload = X-AD80-Timestamp + "." + X-AD80-Delivery + "." + raw_body
signature = hex( HMAC-SHA256( secret, signed_payload ) )
X-AD80-Signature: v1=<signature>[,v1=<signature of the second secret>]

To verify:

  1. Read the raw request body as bytes, exactly as received. Do not parse and re-serialize the JSON first.
  2. Read X-AD80-Timestamp, X-AD80-Delivery and X-AD80-Signature.
  3. Reject the request if the timestamp is more than 5 minutes away from your clock (in either direction). This is the replay window.
  4. Compute the HMAC-SHA256 of timestamp + "." + deliveryId + "." + rawBody with your secret, as lowercase hex.
  5. Accept if it equals any v1= entry of X-AD80-Signature (compare in constant time). During a secret rotation the header has two entries, and you may hold two secrets: accept a match of any entry with any of your secrets.
  6. Answer 2xx quickly, then process. De-duplicate on X-AD80-Delivery (see Delivery, retries and idempotency).
// Node 18+, Express 4 or 5. npm install express
import crypto from 'node:crypto';
import express from 'express';
// During a rotation, list both secrets until you have called retire-secrets.
const SECRETS = [process.env.AD80_WEBHOOK_SECRET];
const REPLAY_WINDOW_S = 300;
function verifyAd80(rawBody, timestamp, deliveryId, signatureHeader) {
const ts = Number(timestamp);
if (!Number.isInteger(ts) || Math.abs(Date.now() / 1000 - ts) > REPLAY_WINDOW_S) return false;
const given = (signatureHeader || '')
.split(',')
.map((s) => s.trim())
.filter((s) => s.startsWith('v1='))
.map((s) => Buffer.from(s.slice(3), 'hex'));
for (const secret of SECRETS) {
const want = crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${deliveryId}.`)
.update(rawBody)
.digest();
if (given.some((g) => g.length === want.length && crypto.timingSafeEqual(g, want))) return true;
}
return false;
}
const app = express();
// express.raw keeps the exact bytes; do not use express.json() on this route.
app.post('/webhooks/ad80', express.raw({ type: 'application/json' }), (req, res) => {
const ok = verifyAd80(
req.body,
req.get('X-AD80-Timestamp'),
req.get('X-AD80-Delivery'),
req.get('X-AD80-Signature'),
);
if (!ok) return res.status(401).send('bad signature');
const deliveryId = req.get('X-AD80-Delivery');
const event = JSON.parse(req.body.toString('utf8'));
// TODO: skip if deliveryId was already processed, else store it and queue the work.
console.log(deliveryId, event.type);
res.sendStatus(204);
});
app.listen(3000);
  • Verifying parsed JSON. Frameworks that parse the body for you change spacing and key order. Always sign the raw bytes.
  • Forgetting the delivery id. The signed text is timestamp.deliveryId.body, not timestamp.body.
  • Only checking the first v1= entry. During a rotation the header carries two signatures.
  • Comparing with ==. Use a constant-time comparison.
  • A skewed server clock. Keep your clock in sync (NTP); otherwise valid requests fall outside the 5-minute window.