Documentation

Webhooks

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

Event types

Headers

• BehalfID-Event-ID contains the stable event ID for deduplication.
• BehalfID-Timestamp is included in the HMAC base string.
• BehalfID-Signature is formatted as v1=<hex_hmac>.

Retries, DLQ, and replay

Webhook events are queued before delivery. Failed deliveries retry with bounded exponential backoff, then move to a dead-letter state where they can be inspected and replayed from the dashboard.

Delivery is at least once. Receivers should deduplicate by event ID and make side effects idempotent.

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

const valid = await verifyWebhookSignature({
  secret: process.env.BEHALFID_WEBHOOK_SECRET!,
  payload: rawBody,
  timestamp,
  signature
});