Anatomy of a Delivery

{
  "schemaVersion": 1,
  "event": "referral.accepted",
  "eventId": "3f9d2c1e-7b44-4a1c-9e0b-2c5f1a8d6e21",
  "occurredAt": "2026-09-03T14:12:09.401Z",
  "perspective": "sent",
  "piiMasked": false,
  "recipientFirmId": "a1b2c3d4-0000-4000-8000-000000000001",
  "referralId": "6f0b8c2a-1d3e-4f5a-8b7c-9d0e1f2a3b4c",
  "baseCaseId": "2a91c4d6-8e7f-4a1b-9c2d-3e4f5a6b7c8d",
  "referenceNumber": "ACME-0042-BLF",
  "referringFirm": { "id": "a1b2c3d4-0000-4000-8000-000000000001", "name": "Acme Injury Law" },
  "referentFirm":  { "id": "a1b2c3d4-0000-4000-8000-000000000002", "name": "Bay Legal Firm" },
  "isTestCase": false,
  "actor": { "firmId": "a1b2c3d4-0000-4000-8000-000000000002", "source": "manual" },
  "data": { "...": "event-specific, see the event catalog" }
}

# Delivery log for a subscription: status, attempts, last code, last error. Never the payload.
curl "https://api.casexchange.com/api/public/v1/webhooks/{id}/deliveries?page=1&limit=20" \
  -H "X-API-Key: cxp_ro_your_key_here"

const express = require("express");
const { verify } = require("./verify"); // see Verifying signatures

const app = express();

app.post(
  "/casexchange",
  express.raw({ type: "application/json" }), // raw bytes, not parsed JSON
  async (req, res) => {
    // 1. Verify the signature on the exact bytes, before JSON.parse.
    //    A non-2xx makes CaseXchange retry, re-signed with the current secret.
    const signature = req.get("X-CaseXchange-Signature");
    if (!verify(req.body, signature, process.env.CASEXCHANGE_WEBHOOK_SECRET)) {
      return res.status(401).end();
    }

    // 2. Deduplicate on the delivery id (stable across retries).
    const deliveryId = req.get("X-CaseXchange-Delivery");
    const isNew = await store.insertIfAbsent(deliveryId, req.body);

    // 3. Acknowledge as soon as the body is durably stored.
    res.status(200).end();
    if (!isNew) return;

    // 4. Do the real work outside the request.
    await queue.enqueue(deliveryId);
  }
);

// Worker: apply by occurredAt, never by arrival order.
async function processDelivery(deliveryId) {
  const envelope = JSON.parse(await store.rawBody(deliveryId));

  if (envelope.event === "webhook.test") return;          // not an envelope
  if (envelope.recipientFirmId !== MY_FIRM_ID) return;    // not built for us
  if (envelope.isTestCase) return;                        // or route to a sandbox

  const last = await db.lastAppliedAt(envelope.referralId);
  if (last && last > envelope.occurredAt) return;         // stale: a newer event was already applied

  await apply(envelope);                                  // branch on envelope.event
  await db.markApplied(envelope.referralId, envelope.occurredAt);
}