Verdict Capture Webhooks

# 1. In the Verdict Capture dashboard: Settings -> Webhooks -> Add an endpoint (HTTPS URL)
#
# 2. Choose its events:
#    - verification.completed   a photo check finished, compliant or not
#    - inspection.submitted     an inspection link was submitted and processed
#    - inspection.reviewed      someone recorded a review decision on an inspection
#    - inspection.decision      a lending inspection got its automatic decision
#
# 3. Copy the signing secret (whsec_...). It is shown once.
#    "Send test event" delivers a signed webhook.test to the endpoint.

const crypto = require("node:crypto");
const express = require("express");
const { Pool } = require("pg");
const db = new Pool({ connectionString: process.env.DATABASE_URL });
const app = express();
const SIGNING_SECRET = process.env.VERIFY_AI_WEBHOOK_SECRET; // whsec_...

// Create this PostgreSQL table before starting the receiver:
// CREATE TABLE verifyai_webhook_inbox (
//   delivery_id text PRIMARY KEY, event text NOT NULL, payload jsonb NOT NULL,
//   received_at timestamptz NOT NULL DEFAULT now(), processed_at timestamptz
// );
// A worker polls rows WHERE processed_at IS NULL and marks them only after
// successful processing. Retry failed work; make business effects idempotent.
// If forwarding to another queue, mark processed only after durable enqueue.
// Never store a duplicate receipt separately from the work obligation.

// X-VerifyAI-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">
function verifyVerifyAISignature(rawBody, signatureHeader, secret, toleranceSeconds = 300) {
  if (typeof rawBody !== "string" && !Buffer.isBuffer(rawBody)) return false;
  let t = "";
  let v1 = "";
  for (const part of String(signatureHeader || "").split(",")) {
    const [key, value = ""] = part.trim().split("=");
    if (key === "t") t = value;
    if (key === "v1") v1 = value;
  }
  if (!/^[0-9]+$/.test(t) || !/^[0-9a-f]{64}$/i.test(v1)) return false;
  // A timestamp more than five minutes from now is a replay: reject it.
  if (Math.abs(Date.now() / 1000 - Number(t)) > toleranceSeconds) return false;
  const expected = crypto
    .createHmac("sha256", secret)
    .update(t + ".")
    .update(rawBody) // the exact bytes received, never re-serialized JSON
    .digest();
  return crypto.timingSafeEqual(expected, Buffer.from(v1, "hex"));
}

app.post("/webhooks/verifyai", express.raw({ type: "application/json" }), async (req, res) => {
  if (!verifyVerifyAISignature(req.body, req.get("X-VerifyAI-Signature"), SIGNING_SECRET)) {
    return res.status(401).send("invalid signature");
  }
  const deliveryId = req.get("X-VerifyAI-Delivery");
  if (!deliveryId) return res.status(400).send("missing delivery id");
  let payload;
  try { payload = JSON.parse(req.body.toString("utf8")); }
  catch { return res.status(400).send("invalid JSON"); }
  const { event, data } = payload;
  if (event === "webhook.test") return res.status(200).send("ok");
  try {
    // verification.completed, inspection.submitted, inspection.reviewed,
    // inspection.decision (keep the highest data.sequence per inspection_id).
    await db.query("INSERT INTO verifyai_webhook_inbox (delivery_id, event, payload) VALUES ($1, $2, $3::jsonb) ON CONFLICT (delivery_id) DO NOTHING", [deliveryId, event, JSON.stringify(data)]);
    return res.status(200).send("ok"); // committed or already durably recorded
  } catch {
    return res.status(503).send("inbox unavailable"); // Verify will retry
  }
});
app.listen(3000);