Documentation

Webhooks

Subscribe to verification, agent, and permission events. BehalfID signs each event and delivers through a durable outbox.

Event types

verification.allowedverification.deniedagent.createdagent.disabledagent.enabledagent.key_rotatedpermission.createdpermission.revoked

Payload structure

webhook event

{
  "eventId": "evt_xxx",
  "type": "verification.denied",
  "agentId": "agent_xxx",
  "requestId": "req_xxx",
  "decision": {
    "allowed": false,
    "reason": "Amount exceeds maxAmount constraint.",
    "risk": "high"
  },
  "timestamp": "2026-05-18T12:00:00Z"
}

Verify signatures

receiver.ts

import { verifyWebhookSignature } from "@behalfid/sdk";

const isValid = verifyWebhookSignature(
  process.env.BEHALFID_WEBHOOK_SECRET!,
  rawBody,
  request.headers.get("X-BehalfID-Signature")!
);

if (!isValid) {
  return new Response("Unauthorized", { status: 401 });
}