Webhook payload reference

Billixi sends signed JSON after eligible domain changes. Deliveries are at least once and can arrive out of order. Verify the raw bytes, deduplicate by the signed event ID, then fetch current state before acting.

Public agent API reference · Connections and webhook testing

Setup

  1. Sign in and create a personal webhook in Connections with a public HTTPS destination and explicit event selection.
  2. Save the whsec_ signing secret when shown once. Keep it on the receiver server. Rotation immediately replaces the old secret.
  3. Send a synthetic test event. Its initial 202 response means queued; inspect delivery detail for the actual receiver outcome.
  4. Return 2xx after verifying and durably recording the event ID. Handle business work asynchronously.

Webhook destination management uses a human session through the Nuxt BFF. Agent API keys cannot create, rotate, pause or replay subscriptions.

V2 signature verification

Billixi-Signature-V2: t=<unix seconds>,v2=<64 lowercase hex>This header carries a Unix timestamp and 64 lowercase hex characters. HMAC-SHA256 covers the ASCII timestamp, a period, then the exact raw request bytes. Decode the whsec_ suffix as Base64URL key material. Require one well-formed timestamp and digest, compare in constant time, reject timestamps beyond five minutes, and require Billixi-Event-Id to equal the verified JSON body ID. The snippets also check duplicate IDs; production receivers need a persistent unique-key inbox.

Loading verifier example…

The downloadable verifier bundle is generated from executable source. Use the shared V2 vector for local checks.

Event types and envelope

Every body has id, type, schemaVersion, createdAt, livemode, test and an event-specific data object. The event list and required envelope keys below come from the shared published schema. IDs and body bytes remain stable across retries and replay.

Required envelope fields: . One example event body:

{"id":"evt_00000000000040008000000000000001","type":"support.ticket.created","schemaVersion":"1","createdAt":"2026-09-30T10:00:00Z","livemode":false,"test":false,"data":{"ticketId":"00000000-0000-4000-8000-000000000002","status":"open"}}

Per-event source, ownership and recipient scope are documented in the repository integration guide; support tickets exclude internal staff comments.

Delivery, retries and replay

The worker attempts the receiver at most five times: immediately, then after 1 minute, 5 minutes, 30 minutes and 2 hours. Any 2xx succeeds. Timeouts, network failures, 408, 429 and 5xx retry; other 4xx stop. A timeout has an unknown receiver outcome, so deduplicate before effects. Valid Retry-After can extend the schedule up to 24 hours. Manual replay preserves event ID and body, but starts a new delivery generation at the original destination. Pause or removal stops eligible future delivery; a request already in flight cannot be recalled.

Management and testing

Use the signed-in Connections and webhook testing page. Create, edit, rotate, pause, remove, test and replay pass through /api/personal-webhooks with a current human session and owner authorization. A test requires expectedRevision, subscribed eventType and a unique UUID operationId; an exact retry returns the same event. Per-subscription limits may return 429 with Retry-After: 60; a dependency outage returns 503. Delivery detail distinguishes queued, retried, sent and failed.

Compatibility and safety

V2 is the recommended signature. Legacy Billixi-Signature and X-Webhook-Signature remain the raw-body HMAC for existing consumers. Future payload fields may be added; use schemaVersion to handle incompatible changes. Treat event data as untrusted input, avoid logging secrets or sensitive body fields, and use an HTTPS receiver with normal TLS verification. The isolated loopback receiver exception is for local tests only.