Webhooks

curl -X POST https://app.veriticity.com/v1/webhooks \
  -H "Authorization: Bearer $VERITICITY_ORG_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://hooks.example.com/veriticity",
    "description": "Production ledger sync",
    "subscribedTypes": ["purchase.approved", "purchase.rejected", "budget.exhausted"]
  }'

{
  "id": "0199a4b2-7c31-7e50-a1f2-9d3b8c6e4a05",
  "url": "https://hooks.example.com/veriticity",
  "status": "ACTIVE",
  "subscribedTypes": ["purchase.approved", "purchase.rejected", "budget.exhausted"],
  "apiVersion": "2026-09-01",
  "consecutiveFailures": 0,
  "secret": "cmp_whs_Kp8Qw3pZx7mN2vB4cD6fG9hJ1kL3nP5rS7tU9wX0yZ2"
}

{
  "id": "0199a3f1-8c2e-7b40-9f31-6d2e5a1c0b77",
  "type": "purchase.approved",
  "apiVersion": "2026-09-01",
  "createdAt": "2026-09-12T14:03:21.114Z",
  "accountId": "0198c2d4-1a3b-7c50-8e21-4f9a2b6d8e10",
  "data": {
    "purchaseRequestId": "0199a3f1-8c2e-7b40-9f31-6d2e5a1c0b77",
    "approvalRequestId": "0199a3f2-1b4d-7a20-8c31-2e5f7a9b1c40",
    "resolvedBy": "HUMAN",
    "agentId": "0199a3d1-5e6f-7a80-9b10-3c4d5e6f7a80",
    "agentName": "Build pipeline",
    "merchant": "Acme Cloud",
    "amountMinor": "42000",
    "currency": "GBP"
  }
}

Veriticity-Webhook-Id:         0199a3f1-8c2e-7b40-9f31-6d2e5a1c0b77
Veriticity-Webhook-Delivery:   0199a3f5-2d6e-7b91-a042-8f1c3e5d7b60
Veriticity-Webhook-Timestamp:  1789394601
Veriticity-Webhook-Signature:  v1=3Qm8xZ...

v1:{timestamp}:{raw body bytes}

import { Webhooks, isKnownWebhookEvent } from "@veriticity/sdk/webhooks";

const webhooks = new Webhooks({
  // An array while a rotation is in flight: either secret verifies.
  secret: process.env.VERITICITY_WEBHOOK_SECRET!,
});

export async function POST(request: Request) {
  let event;

  try {
    // Verifies and parses together, from the bytes as they arrived.
    event = await webhooks.unwrap(request);
  } catch {
    return new Response(null, { status: 400 });
  }

  // Deduplicate on event.id: delivery is at-least-once.
  if (await alreadyHandled(event.id)) {
    return new Response(null, { status: 204 });
  }

  if (isKnownWebhookEvent(event) && event.type === "purchase.approved") {
    // event.data is narrowed to this event's payload.
    await recordApproval(event.data.purchaseRequestId);
  }

  return new Response(null, { status: 204 });
}

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

const TOLERANCE_SECONDS = 5 * 60;

/**
 * Verify a Veriticity webhook.
 *
 * rawBody must be the exact bytes that arrived. JSON.parse followed by
 * JSON.stringify is not the identity function, and a re-serialised body will
 * not verify.
 */
export function verifyWebhook(
  rawBody: string,
  headers: Headers,
  secret: string,
  now: Date = new Date(),
): boolean {
  const timestamp = headers.get("veriticity-webhook-timestamp");
  const signatureHeader = headers.get("veriticity-webhook-signature");

  if (timestamp === null || signatureHeader === null) {
    return false;
  }

  // Reject anything too far from our own clock, in either direction, so a
  // captured request cannot be replayed tomorrow.
  const age = Math.abs(Math.floor(now.getTime() / 1000) - Number(timestamp));
  if (!Number.isFinite(age) || age > TOLERANCE_SECONDS) {
    return false;
  }

  // The version is inside the signed material, not only in the header.
  const signed = `v1:${timestamp}:${rawBody}`;
  const expected = createHmac("sha256", secret)
    .update(signed, "utf8")
    .digest("base64url");

  // During the 24 hours after a rotation the header carries two signatures.
  // Verifying against either is a success.
  return signatureHeader
    .split(",")
    .map((part) => part.trim())
    .filter((part) => part.startsWith("v1="))
    .map((part) => part.slice(3))
    .some((candidate) => {
      const a = Buffer.from(candidate);
      const b = Buffer.from(expected);

      // timingSafeEqual throws on a length mismatch rather than returning
      // false, so the lengths are compared first.
      return a.length === b.length && timingSafeEqual(a, b);
    });
}

import express from "express";

const app = express();

// The raw body, not a parsed one. Most frameworks parse JSON by default and
// discard the bytes -- that is the single most common reason a first webhook
// integration fails to verify.
app.post(
  "/veriticity",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const rawBody = req.body.toString("utf8");

    if (!verifyWebhook(rawBody, new Headers(req.headers as never), SECRET)) {
      return res.status(400).send("bad signature");
    }

    const event = JSON.parse(rawBody);

    // Deduplicate on the event id. Delivery is at-least-once, so the same
    // event can arrive more than once and you will see it eventually.
    if (alreadyHandled(event.id)) {
      return res.status(200).send("ok");
    }

    // Acknowledge quickly, then do the work. Veriticity gives you 10 seconds.
    res.status(200).send("ok");
    void handleAsync(event);
  },
);