Webhooks

// Verify a webhook delivery (Node.js 18 or later, no dependencies).
import { createHash, createHmac, timingSafeEqual } from 'node:crypto';

const TOLERANCE_SECONDS = 300;
// Deliveries already accepted (a digest of the timestamp and the body), each kept until its
// timestamp is too old to be accepted anyway. With several processes, keep them in your database.
const seen = new Map();

/**
 * header:  the CC-Signature request header
 * rawBody: the request body exactly as received (a Buffer or a string)
 * secrets: your endpoint secret, or [new, old] while a rotation is under way
 * Returns true only for a genuine delivery that has not been seen before.
 */
export function verifyWebhook(header, rawBody, secrets, nowMs = Date.now()) {
  let t = null;
  const v1 = [];
  for (const part of String(header ?? '').split(',')) {
    const [k, v = ''] = part.split('=').map((s) => s.trim());
    if (k === 't' && /^[0-9]{1,12}$/.test(v)) t = Number(v);
    else if (k === 'v1' && /^[0-9a-f]{64}$/.test(v)) v1.push(v);
  }
  if (t === null || v1.length === 0) return false;
  const now = Math.floor(nowMs / 1000);
  if (Math.abs(now - t) > TOLERANCE_SECONDS) return false;
  const body = Buffer.isBuffer(rawBody) ? rawBody : Buffer.from(rawBody);
  const genuine = [secrets].flat().some((secret) => {
    const want = createHmac('sha256', secret).update(`${t}.`).update(body).digest();
    return v1.some((got) => timingSafeEqual(want, Buffer.from(got, 'hex')));
  });
  if (!genuine) return false;
  // A replay is the same timestamp and body, whichever of its signatures it still carries:
  // during a rotation a delivery has two, and resending it with only one is still a replay.
  const key = createHash('sha256').update(`${t}.`).update(body).digest('hex');
  for (const [k, until] of seen) if (until < now) seen.delete(k);
  if (seen.has(key)) return false;
  seen.set(key, t + TOLERANCE_SECONDS);
  return true;
}

// With node:http:
//   const chunks = [];
//   req.on('data', (c) => chunks.push(c)).on('end', () => {
//     const raw = Buffer.concat(chunks);
//     if (!verifyWebhook(req.headers['cc-signature'], raw, process.env.CC_WEBHOOK_SECRET)) return res.writeHead(401).end();
//     res.writeHead(204).end();
//     handle(JSON.parse(raw)); // a retry is a new delivery: use the CC-Event-Id header to ignore an event you already handled
//   });