Webhooks

Webhooks are signed with the Standard Webhooks scheme — the same scheme AgentMail uses via Svix — so existing Svix verification code works unchanged.

Endpoints

• GET /v0/webhooks · POST /v0/webhooks — org-wide
• GET /v0/webhooks/{id} · PATCH /v0/webhooks/{id} · DELETE /v0/webhooks/{id}
• GET /v0/webhooks/{id}/headers · PATCH /v0/webhooks/{id}/headers — custom headers
• Inbox-scoped mirrors under /v0/inboxes/{inbox_id}/webhooks…

Create a webhook

curl -X POST https://api.wzrd.tech/v0/webhooks \
  -H "Authorization: Bearer $WZRDMAIL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://example.com/api/inbound/email", "event_types": ["message.received"], "client_id": "wh-1"}'

The response includes a whsec_ signing secret, shown once.

Event envelope

Every state change emits exactly one immutable event:

{
  "event_id": "evt_01J…",
  "type": "message.received",
  "created_at": "2026-08-31T17:04:05Z",
  "organization_id": "org_…",
  "pod_id": "pod_…",
  "inbox_id": "scout@wzrd.tech",
  "data": { "message": { "…": "full message object, extracted_text included" } }
}

Event types: message.received, message.sent, message.delivered, message.bounced, message.complained, message.rejected, domain.verified.

Verifying signatures

Deliveries carry svix-id, svix-timestamp, and svix-signature headers (v1, + base64 HMAC-SHA256 over {id}.{timestamp}.{payload} with your whsec_ secret). Any Svix / Standard Webhooks verification library verifies them unchanged.

Delivery & retries

POST with a 10 s timeout; success is any 2xx. Retries at 30 s, 5 m, 30 m, 2 h, 8 h, then dead-letter. Deliveries are idempotent by event id — dedupe on event_id in your handler.