Webhooks overview

import express from "express";
import { Webhook } from "svix";

const app = express();
const webhook = new Webhook(process.env.BOTSHIELD_WEBHOOK_SECRET!); // whsec_…

// Stand-in for your database. Use a unique constraint in production.
const processed = new Set<string>();

// One endpoint receives both environments. Set this to "development" on your test deployment.
const ENVIRONMENT = process.env.BOTSHIELD_ENVIRONMENT ?? "production";

type BotShieldEvent = {
  type: string;
  request_id?: string; // absent on account.unlinked
  environment?: "development" | "production"; // on gate events
  event_id?: string;
  resolution_id?: string;
  card_id?: string;
  [key: string]: unknown;
};

// express.raw() keeps the body as a Buffer. Do not use express.json() on this route.
app.post("/webhooks/botshield", express.raw({ type: "application/json" }), (req, res) => {
  let event: BotShieldEvent;
  try {
    event = webhook.verify(req.body, {
      "svix-id": req.header("svix-id") ?? "",
      "svix-timestamp": req.header("svix-timestamp") ?? "",
      "svix-signature": req.header("svix-signature") ?? "",
    }) as BotShieldEvent;
  } catch {
    res.status(400).send("Invalid signature");
    return;
  }

  // One key per logical event. See "Deduplicate" below.
  // account.unlinked (3.0) has none of these IDs, so fall back to the svix-id header.
  const dedupeKey = `${event.type}:${
    event.resolution_id ?? event.card_id ?? event.request_id ?? req.header("svix-id")
  }`;
  if (processed.has(dedupeKey)) {
    res.status(204).end();
    return;
  }
  processed.add(dedupeKey);

  // Acknowledge first, then do the work.
  res.status(204).end();
  void handleEvent(event);
});

async function handleEvent(event: BotShieldEvent): Promise<void> {
  // Gate events say which environment they came from. Skip the other one.
  if (event.environment && event.environment !== ENVIRONMENT) return;

  switch (event.type) {
    case "gate.human_verified":
      // Mark the order or session for event.request_id as verified.
      break;
    case "gate.unavailable":
      // Keep the action blocked. Offer the user another try.
      // event.reason says why a failure happened. An expiry has no reason.
      break;
    case "agents_ask.resolution.confirmed":
      // Verify event.proof_token, then let the agent proceed.
      break;
    case "agents_ask.resolution.denied":
    case "agents_ask.resolution.expired":
      // Stand the agent down.
      break;
    case "account.unlinked":
      // Mark the account for event.handle as no longer trusted.
      break;
  }
}

app.listen(3000);

// app/api/webhooks/botshield/route.ts
import { Webhook } from "svix";

const webhook = new Webhook(process.env.BOTSHIELD_WEBHOOK_SECRET!);

export async function POST(request: Request): Promise<Response> {
  const payload = await request.text(); // raw body, exactly as sent

  let event: { type: string; request_id?: string };
  try {
    event = webhook.verify(payload, {
      "svix-id": request.headers.get("svix-id") ?? "",
      "svix-timestamp": request.headers.get("svix-timestamp") ?? "",
      "svix-signature": request.headers.get("svix-signature") ?? "",
    }) as { type: string; request_id?: string };
  } catch {
    return new Response("Invalid signature", { status: 400 });
  }

  await enqueue(event); // hand off to a queue or background job; keep this fast
  return new Response(null, { status: 204 });
}

async function enqueue(event: { type: string; request_id?: string }): Promise<void> {
  // Deduplicate, then store the event for processing.
}