Scribble webhooks: get notified when a card is mailed

{
  "id": "evt_4EPtVoVpsetMu5taYHXsW3Jc",
  "data": {
    "card": "SC-H9BYHDA",
    "recipient": "Sam Ortiz",
    "reference": "crm-4471",
    "heldReason": null
  },
  "type": "card.created",
  "created": "2026-08-05T09:39:56.883Z"
}

import crypto from "node:crypto";

export function verifyScribbleSignature(rawBody, signatureHeader, signingSecret) {
  const parts = Object.fromEntries(
    signatureHeader.split(",").map((p) => {
      const i = p.indexOf("=");
      return [p.slice(0, i).trim(), p.slice(i + 1).trim()];
    }),
  );
  if (!parts.t || !parts.v1) return false;

  // Reject anything older than five minutes so a captured delivery
  // cannot be replayed at you later.
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false;

  const expected = crypto
    .createHmac("sha256", signingSecret)
    .update(`${parts.t}.${rawBody}`)
    .digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(parts.v1, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

import express from "express";

const app = express();

// express.json() would consume the stream and leave you with a parsed
// object you cannot re-serialise byte-for-byte. Capture the raw buffer.
app.post(
  "/webhooks/scribble",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    const ok = verifyScribbleSignature(
      raw,
      req.get("scribble-signature") ?? "",
      process.env.SCRIBBLE_WEBHOOK_SECRET,
    );
    if (!ok) return res.status(400).send("bad signature");

    // Acknowledge FIRST, work afterwards. The delivery times out at
    // ten seconds and a slow handler just earns you a retry.
    res.status(200).send("ok");

    const event = JSON.parse(raw);
    void handleAsync(event);
  },
);

import hmac, hashlib, time

def verify_scribble_signature(raw_body: bytes, signature_header: str, signing_secret: str) -> bool:
    parts = dict(p.split("=", 1) for p in signature_header.split(","))
    if "t" not in parts or "v1" not in parts:
        return False
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    signed = parts["t"].encode() + b"." + raw_body
    expected = hmac.new(signing_secret.encode(), signed, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])