Webhook Event Payloads

This page documents the wire-level shape of an Orbit webhook delivery — the request envelope, the headers Orbit sends, and the metadata Orbit captures about every delivery attempt (including the request headers sent and the response headers received from your endpoint). For the full catalog of event types (message.delivered, call.completed, …) see Webhook Events. For HMAC signature verification see Webhook Security.

Request envelope

Every delivery is a single HTTP POST with a JSON body that follows the canonical envelope:

{
  "id": "evt_3f1c8b2a9d4e5f7a8b6c1d2e3f4a5b6c",
  "type": "message.delivered",
  "created_at": "2026-05-24T12:00:00Z",
  "data": {
    "message_id": "msg_xyz789",
    "channel": "sms",
    "timestamp": "2026-05-24T12:00:00Z",
    "status": "delivered",
    "state_class": "terminal",
    "is_terminal": true
  }
}

The data shape above is a successful delivery. Terminal-failure payloads (message.failed, which also covers the expired / submitted_no_receipt transitions) additionally carry optional error_code and error_message strings when the message has a provider-supplied failure reason — the raw code and text the carrier / channel returned. They are absent (not null) when no provider error was captured, and successful transitions clear them. See the webhook events reference for the full failure payload shape.

Field	Type	Notes
`id`	string	Stable event id. Use this for idempotency / dedup — at-least-once delivery means the same event may arrive twice (e.g. when your endpoint timed out the first send).
`type`	string	Event-type name from the event catalog.
`created_at`	string	ISO-8601 timestamp when the event was emitted on Orbit’s side.
`data`	object	Event-specific payload. The exact shape per event type is documented in the webhook events reference.

Request headers

Orbit sends every delivery with the following headers:

Header	Value	Notes
`Content-Type`	`application/json`	No `charset` parameter is sent.
`User-Agent`	`Devotel-Webhook/1.0`	Static (note: singular `Webhook`). Use this for ACL allowlisting if your receiver gates by UA.
`X-Devotel-Signature`	`t=<unix>,v1=<hex>[,v1=<hex>]`	HMAC-SHA256 (legacy back-compat header; carries dual `v1=new,v1=old` during a key-rotation grace window). See Webhook Security.
`X-Devotel-Timestamp`	`<unix seconds>`	Signing timestamp — the same `t=` value embedded in `X-Devotel-Signature`.
`X-Devotel-Event`	`<event type>`	Mirrors `body.type`.
`X-Devotel-Delivery`	`<event id>`	Mirrors `body.id`. Some receivers (e.g. Cloudflare Workers) prefer to deduplicate from a header.
`Idempotency-Key`	`<event id>`	Equals `body.id`. Stable across every retry of the same event — use it for safe dedup when Orbit retries after an ambiguous outcome (our socket timed out but your endpoint already `2xx`’d).
`X-Devotel-Attempt`	`<0-based counter>`	`0` on the first delivery, incremented by one on each retry.
`X-Orbit-Signature`	`t=<unix>,v1=<hex>`	Canonical signature (single matched key). Present whenever a canonical signature is available. See Webhook Security.
`X-Orbit-Signature-Next`	`t=<unix>,v1=<hex>`	Rotation-candidate signature. Sent only during a key-rotation grace window, so verifiers that want to discriminate which key matched can do so cleanly.

Inspecting delivery attempts

Orbit persists metadata about every delivery attempt (request headers sent, response status, response body, response headers received). Operators can inspect these via the dashboard or the API:

GET /api/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}

Authentication: Clerk session or API key with webhooks:read scope. 200 OK

{
  "data": {
    "id": "wdl_3f1c8b2a9d4e5f7a8b6c",
    "endpoint_id": "wh_abc123",
    "event_type": "message.delivered",
    "event_id": "evt_xyz789",
    "status": "delivered",
    "http_code": 200,
    "latency_ms": 142,
    "attempts": 1,
    "next_retry_at": null,
    "last_response_status": 200,
    "last_response_body": "{\"ok\":true}",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "Devotel-Webhook/1.0",
      "X-Devotel-Signature": "t=1715357600,v1=4f9c2e6b...",
      "X-Devotel-Timestamp": "1715357600",
      "X-Devotel-Event": "message.delivered",
      "X-Devotel-Delivery": "evt_xyz789",
      "Idempotency-Key": "evt_xyz789",
      "X-Devotel-Attempt": "0",
      "X-Orbit-Signature": "t=1715357600,v1=4f9c2e6b...",
      "Authorization": "<redacted>"
    },
    "response_headers": {
      "Content-Type": "application/json",
      "X-Request-Id": "your-trace-id-xyz",
      "Cache-Control": "no-store"
    },
    "payload": {
      "id": "evt_xyz789",
      "type": "message.delivered",
      "created_at": "2026-05-24T12:00:00Z",
      "data": { "message_id": "msg_xyz789", "channel": "sms", "timestamp": "2026-05-24T12:00:00Z", "status": "delivered", "state_class": "terminal", "is_terminal": true }
    },
    "created_at": "2026-05-24T12:00:00Z",
    "updated_at": "2026-05-24T12:00:00Z",
    "completed_at": "2026-05-24T12:00:00Z"
  },
  "meta": { "request_id": "req_abc123", "timestamp": "2026-05-24T12:00:00Z" }
}

`request_headers` (captured since 2026-04, migration 217)

The exact header set Orbit sent on this delivery attempt. Useful for self-serve HMAC debugging — operators can inspect the X-Devotel-Signature value Orbit signed against and compare it to what their receiver computed. Redaction. Orbit redacts the value of any request header matching its secret denylist before persisting (the header name is preserved; only the value becomes <redacted>). Matching is case-insensitive. The full denylist is:

Authorization
Proxy-Authorization
Cookie
X-Api-Key
X-Auth-Token
X-CSRF-Token
X-Amz-Security-Token
Any header whose name matches X-*-Secret (starts with X-, ends with -Secret)
Any header whose name matches X-*-Token (starts with X-, ends with -Token)
Any header whose name matches X-*-Key (starts with X-, ends with -Key)

X-Devotel-Signature is deliberately not redacted — you need its plaintext HMAC digest to debug signature reconstruction. The redaction is one-way — once persisted, the original values are unrecoverable from the delivery row. This is intentional: the deliveries API is read-only and operator-facing; raw secrets must not surface in dashboard render paths even via inspect.

`response_headers` (captured since 2026-07-01)

The header set returned by your endpoint on this delivery attempt. Useful for:

Debugging your receiver’s CDN / WAF chain (e.g. confirming Cloudflare didn’t strip your body).
Correlating with your own logging — many receivers echo a request id (X-Request-Id / Traceparent) that the deliveries view can surface.
Validating that your receiver returned the expected Cache-Control: no-store for webhook responses.

Only headers your endpoint actually returned are captured, up to the first 100 header names (each value truncated to 1,024 characters). Set-Cookie is never persisted — a session cookie your server issues is a credential, so it is dropped before the delivery row is stored. Backwards compatibility. Deliveries recorded before 2026-07-01 (when Orbit began capturing response headers) carry response_headers: null. The dashboard renders a “headers not captured for this delivery” empty-state in that case — it does NOT block render of the delivery row itself.

`last_response_body`

Truncated to the first 500 bytes of the response body. Use for debugging your receiver’s error messages. No truncation marker is appended, so treat the value as potentially clipped whenever it reaches 500 bytes.

Listing recent deliveries

GET /api/v1/webhooks/{endpoint_id}/deliveries

Cursor-paginated. The same request_headers / response_headers fields are returned per row so the dashboard can render the headers panels inline without an extra round-trip per row. Query parameters

Name	Type	Notes
`limit`	integer (1–100)	Default 25.
`cursor`	string	Opaque cursor from the previous response.
`status`	enum	Filter — `success`, `failed`, `pending`.
`event_type`	string	Filter by event type, e.g. `message.delivered`.
`from_date`	string	ISO-8601 lower bound on `created_at`.
`to_date`	string	ISO-8601 upper bound on `created_at` (exclusive).

Replay + retry

If your endpoint was down or returned a non-2xx, Orbit retries on the delivery schedule. To force a replay of an already-completed delivery (e.g. after a downstream bug fix):

POST /api/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/replay

Creates a new delivery row with the same event_id and payload and queues it for immediate dispatch. The original row is preserved as audit trail. To re-queue a failed delivery (without changing the payload):

POST /api/v1/webhooks/{endpoint_id}/deliveries/{delivery_id}/retry

Resets the delivery’s status to pending and sets next_retry_at = now() so the worker picks it up on the next tick.

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Webhook Event Payloads

Webhook Event Payloads

Request envelope

Request headers

Inspecting delivery attempts

`request_headers` (captured since 2026-04, migration 217)

`response_headers` (captured since 2026-07-01)

`last_response_body`

Listing recent deliveries

Replay + retry

See also

​Webhook Event Payloads

​Request envelope

​Request headers

​Inspecting delivery attempts

​request_headers (captured since 2026-04, migration 217)

​response_headers (captured since 2026-07-01)

​last_response_body

​Listing recent deliveries

​Replay + retry

​See also

Webhook Event Payloads

Request envelope

Request headers

Inspecting delivery attempts

`request_headers` (captured since 2026-04, migration 217)

`response_headers` (captured since 2026-07-01)

`last_response_body`

Listing recent deliveries

Replay + retry

See also