Webhook reconciliation

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

const app = express();

const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

if (!WEBHOOK_SECRET) {
  throw new Error("WEBHOOK_SECRET is required");
}

function signatureMatches(rawBody: Buffer, signature: string, secret: string) {
  const expected = createHmac("sha256", secret).update(rawBody).digest("hex");
  const signatureBuffer = Buffer.from(signature, "hex");
  const expectedBuffer = Buffer.from(expected, "hex");
  const hasExpectedLength = signatureBuffer.length === expectedBuffer.length;
  const comparableSignature = hasExpectedLength
    ? signatureBuffer
    : Buffer.alloc(expectedBuffer.length);

  const isMatch = timingSafeEqual(comparableSignature, expectedBuffer);
  return hasExpectedLength && isMatch;
}

app.post(
  "/webhooks/request-network",
  express.raw({ type: "application/json" }),
  async (req, res) => {
    const signature = req.headers["x-request-network-signature"] as string;
    const deliveryId = req.headers["x-request-network-delivery"] as string;

    if (!signature || !deliveryId) {
      return res.status(400).send("missing headers");
    }

    // 1. Verify against the RAW body — never re-stringify.
    const hasValidSignature = signatureMatches(req.body, signature, WEBHOOK_SECRET);

    if (!hasValidSignature) {
      return res.status(401).send("invalid signature");
    }

    // 2. A verified test delivery uses placeholder data. Acknowledge it
    // before it can change application state.
    if (req.headers["x-request-network-test"] === "true") {
      console.info("received verified Request Network test webhook");
      return res.status(200).send("ok");
    }

    try {
      // 3. Parse and route. Each business operation uses deliveryId as an
      // idempotency key in its own durable store.
      const event = JSON.parse(req.body.toString("utf8"));
      console.info({ deliveryId, event: event.event });
      await handleEvent(event, deliveryId);
      return res.status(200).send("ok");
    } catch (err) {
      console.error("handler failed", err);
      return res.status(500).send("handler error");
    }
  },
);

async function handleEvent(event: any, deliveryId: string) {
  switch (event.event) {
    // Hosted onboarding, delivered to an orchestrator endpoint.
    case "client_id.linked":
      await recordLinkedPlatform(
        event.clientId,
        event.linkId,
        event.intentId,
        deliveryId,
      );
      break;

    case "payment.confirmed":
      await markOrderPaid(event.requestId, event.txHash, deliveryId);
      break;

    case "payment.failed":
      await flagFailedPayment(
        event.requestId,
        event.subStatus,
        deliveryId,
      );
      break;

    case "kyt.screening.completed":
      await recordKytResult(
        event.paymentToken,
        event.status,
        event.provider,
        deliveryId,
      );
      break;

    // Payer activity from the Secure Payment Page. Do not use it as a
    // settlement signal; use payment.confirmed instead.
    case "secure_payment.user_event":
      await recordPayerActivity(
        event.securePaymentToken,
        event.userEvent,
        deliveryId,
      );
      break;

    // A payer-wallet allowlist rejection. This is useful for monitoring and
    // audit history, but it does not change the payment's settlement state.
    case "secure_payment.access_rejected":
      await recordPayerWalletRejection(
        event.requestId,
        event.attemptedPayerWalletAddress,
        deliveryId,
      );
      break;

    default:
      // Acknowledge events this handler does not use so they do not retry.
      console.info({ deliveryId, event: event.event }, "ignoring event");
  }
}

async function markOrderPaid(
  requestId: string,
  txHash: string,
  deliveryId: string,
) {
  await db.transaction(async (tx) => {
    const order = await tx.orders.findOne({ where: { requestId } });
    if (!order) return; // not ours

    const claim = await tx.execute(
      `INSERT INTO webhook_deliveries (delivery_id)
       VALUES ($1)
       ON CONFLICT (delivery_id) DO NOTHING`,
      [deliveryId],
    );
    if (claim.rowCount === 0) return; // already applied

    await tx.orders.update({
      where: { id: order.id },
      data: { paidAt: new Date(), txHash },
    });
  });
}

case "payment.failed":
  await fetch(SLACK_WEBHOOK, {
    method: "POST",
    body: JSON.stringify({
      text: `:warning: Payment failed for request ${event.requestId}`,
    }),
  });
  break;

ngrok http 3000
# Pass the https://xxxxx.ngrok-free.app URL when you register your endpoint