Webhooks

{
  "id": "c81b0d5e-4a71-4a1e-9a2f-6f83b1c04e29",
  "url": "https://hooks.example.com/farthing",
  "label": "prod",
  "secret": "whsec_kR7pXvT2mQ9fLbN4hJ8sYc1WdE6aZg0u"
}

{
  "data": [
    {
      "id": "c81b0d5e-4a71-4a1e-9a2f-6f83b1c04e29",
      "url": "https://hooks.example.com/farthing",
      "label": "prod",
      "lastDeliveryAt": "2026-07-29T09:26:29.881Z",
      "lastDeliveryStatus": 200,
      "createdAt": "2026-07-28T14:03:55.204Z"
    }
  ],
  "nextCursor": null
}

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

/**
 * @param {string} secret  the whsec_… value from endpoint creation
 * @param {string} body    the raw request body, exactly as received
 * @param {string} header  the x-checkoutvia-signature header value
 */
export function verifyWebhookSignature(secret, body, header, toleranceSec = 300) {
  const t = /(?:^|,)t=(\d+)/.exec(header)?.[1];
  const v1 = /(?:^|,)v1=([a-f0-9]+)/.exec(header)?.[1];
  if (!t || !v1) return false;
  // Reject stale timestamps so a captured delivery can't be replayed indefinitely.
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSec) return false;
  const expected = createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(v1, "hex");
  return a.length === b.length && timingSafeEqual(a, b);
}

import express from "express";
import { verifyWebhookSignature } from "./verify.js";

const app = express();
const SECRET = process.env.FARTHING_WEBHOOK_SECRET;

app.post(
  "/farthing",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const raw = req.body.toString("utf8");
    const header = req.get("x-checkoutvia-signature") ?? "";
    if (!verifyWebhookSignature(SECRET, raw, header)) {
      return res.status(400).send("bad signature");
    }

    const event = JSON.parse(raw);
    // Acknowledge fast, then do the work out of band. We give you 10 seconds.
    res.status(200).end();
    void handle(event);
  },
);

async function handle(event) {
  if (event.type !== "checkout.status_changed") return;
  const checkout = await fetchCheckout(event.checkoutId); // GET /v1/checkouts/{id}
  // ... your logic
}