Webhooks

Detecte POSTs signed JSON to your URL whenever something interesting happens. Events you can subscribe to:

• action.allowed, action.blocked, action.escalated
• incident.created, incident.resolved
• approval.requested, approval.granted, approval.denied
• agent.tier_changed, agent.verified

Headers

Content-Type: application/json
Detecte-Event: action.blocked
Detecte-Delivery: dlv_abc123…
Detecte-Signature: t=1718900000,v1=8a91…

Verify the signature

import { Detecte } from "@detecte/sdk";
 
const detecte = new Detecte({ apiKey: process.env.DETECTE_API_KEY! });
 
export async function POST(req: Request) {
  const raw = await req.text();
  const sig = req.headers.get("detecte-signature")!;
  const ok = detecte.webhooks.verify({
    payload: raw,
    signature: sig,
    secret: process.env.DETECTE_WEBHOOK_SECRET!,
  });
  if (!ok) return new Response("bad signature", { status: 401 });
 
  const event = JSON.parse(raw);
  // handle event.type
  return new Response("ok");
}

Signatures are HMAC-SHA256 over {timestamp}.{payload}. The 5-minute timestamp tolerance protects against replay.

Retries

Failed deliveries (non-2xx response or network error) are retried with exponential backoff: 1m, 3m, 9m, 27m, 81m. After 5 attempts the delivery is marked dead and visible in the dashboard's webhook log; you can manually retry from there.