Verify a webhook signature

The signing scheme

signed_string = "{timestamp}.{raw_body}"
signature     = HMAC_SHA256(signed_string, signing_secret)
header        = "v1=" + hex(signature)

# timestamp comes from X-CountdownShare-Timestamp
# raw_body is the request body EXACTLY as sent, byte for byte

node:crypto

import { createHmac, timingSafeEqual } from "node:crypto";

// Express: app.post(path, express.raw({ type: "application/json" }), handler)
// The signature covers the RAW body. Parsing it first will break the check.
export function verify(rawBody, headers, secret) {
  const timestamp = headers["x-countdownshare-timestamp"];
  const signature = headers["x-countdownshare-signature"];
  if (!timestamp || !signature) return false;

  // Reject anything older than five minutes — a valid signature
  // captured off the wire is otherwise replayable forever.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;

  const expected = createHmac("sha256", secret)
    .update(`${timestamp}.${rawBody}`)
    .digest("hex");
  const received = signature.replace(/^v1=/, "");

  // Constant-time comparison. === leaks timing information.
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(received, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

hmac + hashlib

import hashlib
import hmac
import time


def verify(raw_body: bytes, headers, secret: str) -> bool:
    timestamp = headers.get("X-CountdownShare-Timestamp")
    signature = headers.get("X-CountdownShare-Signature")
    if not timestamp or not signature:
        return False

    if abs(time.time() - int(timestamp)) > 300:
        return False

    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.".encode() + raw_body,
        hashlib.sha256,
    ).hexdigest()

    received = signature.removeprefix("v1=")
    return hmac.compare_digest(expected, received)

hash_hmac

<?php
function verify(string $rawBody, array $headers, string $secret): bool
{
    $timestamp = $headers['X-CountdownShare-Timestamp'] ?? null;
    $signature = $headers['X-CountdownShare-Signature'] ?? null;

    if (!$timestamp || !$signature) {
        return false;
    }

    if (abs(time() - (int) $timestamp) > 300) {
        return false;
    }

    $expected = hash_hmac('sha256', $timestamp . '.' . $rawBody, $secret);
    $received = preg_replace('/^v1=/', '', $signature);

    return hash_equals($expected, $received);
}

app/api/webhooks/countdownshare/route.ts

// app/api/webhooks/countdownshare/route.ts
//
// Next.js route handlers do not pre-parse the body, so request.text()
// gives you exactly what was sent.
export async function POST(request: Request) {
  const rawBody = await request.text();

  const headers = {
    "x-countdownshare-timestamp": request.headers.get("x-countdownshare-timestamp"),
    "x-countdownshare-signature": request.headers.get("x-countdownshare-signature"),
  };

  if (!verify(rawBody, headers, process.env.COUNTDOWNSHARE_WEBHOOK_SECRET!)) {
    return new Response("Invalid signature", { status: 401 });
  }

  const event = JSON.parse(rawBody);   // parse only AFTER verifying

  await queue.add("countdown-event", event);
  return new Response(null, { status: 200 });
}

Do not do these

// 1. Parsed before verifying — the most common failure by far.
app.use(express.json());                      // body is now an object
app.post("/webhooks", (req, res) => {
  verify(JSON.stringify(req.body), ...);      // key order and whitespace differ
});

// 2. Re-serialising the parsed body. Same problem, harder to spot.
const rawish = JSON.stringify(req.body);      // not the original bytes

// 3. Comparing with ===. Leaks timing information to an attacker.
return expected === received;

// 4. Signing the body alone, without the timestamp prefix.
createHmac("sha256", secret).update(rawBody);  // missing `${timestamp}.`