Webhook payload cookbook: one payload per event family

For each of the nine event families: the exact JSON your endpoint receives, the signature header shape, the dedupe key, and one receiver example. Mechanics (retry schedule, dead-letter, rotation) are deferred to the durable webhook consumer guide; the event catalog page lists all ~300 event types and the events reference carries field-level detail.

Request shape (all families)

POST /webhooks/orbit HTTP/1.1
Content-Type: application/json
X-Orbit-Signature: t=1715357600,v1=4f9c2e6b...<64-hex>
X-Devotel-Signature: t=1715357600,v1=4f9c2e6b...   # back-compat twin

{"id":"evt_abc123","type":"message.delivered","created_at":"…","data":{…}}

Signature header: t=<epoch-seconds>,v1=<hmac-sha256-hex> over ${t}.${raw-body} with your whsec_... secret. Verify with the polyglot signature recipe. During a rotation window the header carries multiple v1 candidates — accept if any matches.
Envelope: { id, type, created_at, data } — id is the dedupe key (stable across retries of the same event, at-least-once delivery). Persist seen ids; a hit is a duplicate, ack 200 and stop.

1. Message lifecycle (`message.*`)

message.expired and message.submitted_no_receipt never dispatch as their own type — they ride on message.failed, branch on data.status. Engagement events (email.opened, email.clicked, short_link.click) are siblings, not lifecycle transitions.

{
  "id": "evt_msq01",
  "type": "message.delivered",
  "created_at": "2026-09-24T12:00:03Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "to": "+14155552671",
    "status": "delivered",
    "state_class": "terminal",
    "is_terminal": true,
    "timestamp": "2026-09-24T12:00:03Z"
  }
}

export function handleMessageEvent(event) {
  const { message_id, status, is_terminal } = event.data;
  updateDeliveryState(message_id, status, is_terminal);
}

2. Voice / call lifecycle (`call.`, `recording.`, `voicemail.*`)

{
  "id": "evt_voc01",
  "type": "call.completed",
  "created_at": "2026-09-24T12:02:22Z",
  "data": {
    "call_id": "call_abc123",
    "provider": "jambonz",
    "provider_call_sid": "CA-4f9c...",
    "direction": "inbound",
    "from": "+14155552671",
    "to": "+18005551234",
    "status": "completed",
    "duration_seconds": 142,
    "hangup_reason": "normal_clearing",
    "sip_response_code": 200,
    "sip_reason": "OK",
    "timestamp": "2026-09-24T12:02:22Z"
  }
}

def handle_call_event(event):
    d = event["data"]
    if event["type"] == "call.completed":
        record_cdr(d["call_id"], d["duration_seconds"], d["hangup_reason"])

3. Porting (`porting.request.*`)

{
  "id": "evt_prt01",
  "type": "porting.request.loa_signed",
  "created_at": "2026-09-24T09:15:00Z",
  "data": {
    "porting_id": "port_001",
    "numbers": ["+14155550100"],
    "signer_name": "Jane Doe",
    "signer_email": "jane@example.com",
    "signed_at": "2026-09-24T09:15:00Z"
  }
}

porting.request.cancelled flips cancelled_from_status; porting.request.manual_review_required adds manual_reason for routing by failure mode.

4. Verify (`verification.*`)

{
  "id": "evt_vfy01",
  "type": "verification.approved",
  "created_at": "2026-09-24T10:00:11Z",
  "data": {
    "verification_id": "vrf_3f1c0b2a8e4d",
    "channel": "sms",
    "to": "+14155552671"
  }
}

channel is sms / voice / silent. verification.checked fires on every persisted attempt — including non-terminal pending — check data.outcome before acting.

5. CDP events (`cdp.`, `contact.`)

{
  "id": "evt_cdp01",
  "type": "cdp.event.ingested",
  "created_at": "2026-09-24T11:00:00Z",
  "data": {
    "event_id": "cdpevt_abc123",
    "type": "track",
    "name": "Order Completed",
    "user_id": "user_42",
    "anonymous_id": "anon_abc",
    "contact_id": "con_abc",
    "properties": { "value": 99.99, "currency": "USD" },
    "received_at": "2026-09-24T11:00:00Z"
  }
}

Opt-outs arrive as contact.opted_in / contact.opted_out with { channel, phone, keyword, timestamp }; segment flips as contact.segment_changed with { contact_id, previous_label, new_label, computed_at }.

6. Delivery receipts (`submitted_no_receipt` / `expired`)

The carrier accepted the submission but never confirmed the handset; both statuses fan out on message.failed.

{
  "id": "evt_dlr01",
  "type": "message.failed",
  "created_at": "2026-09-24T18:00:01Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "status": "submitted_no_receipt",
    "state_class": "intermediate",
    "is_terminal": false,
    "timestamp": "2026-09-24T18:00:01Z"
  }
}

submitted_no_receipt is intermediate — do not mark yourself delivered. expired is terminal. Dedupe stays on envelope id even when one message_id re-reports.

7. Campaign (`campaign.*`)

{
  "id": "evt_cmp01",
  "type": "campaign.drip_step.completed",
  "created_at": "2026-09-24T14:00:00Z",
  "data": {
    "campaign_id": "camp_abc123",
    "step_index": 2,
    "sent": 480,
    "failed": 12
  }
}

8. Flows (`flow.*`)

{
  "id": "evt_flw01",
  "type": "flow.executed",
  "created_at": "2026-09-24T15:00:01Z",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "status": "completed",
    "step_count": 8
  }
}

status is completed, failed, or timeout. Sibling flow.execution.started / .completed / .failed add error and duration_ms.

9. Number lifecycle (`number.*`)

number.purchased / number.released carry { number_id }; a mid-flight amendment arrives as porting.request.supplement_submitted, never as number.ported with a half-status.

{
  "id": "evt_num01",
  "type": "number.ported",
  "created_at": "2026-09-24T16:00:00Z",
  "data": {
    "porting_id": "port_001",
    "numbers": ["+14155550100", "+14155550101"],
    "carrier": "Verizon",
    "provider": "telnyx",
    "status": "completed"
  }
}

Order: verification before the parser

An unauthenticated body is wire noise — parser-first hands attacker bytes to your JSON stack.

Read the raw body bytes (before any JSON parser runs).
Verify X-Orbit-Signature — the one-function-call recipe in seven languages is in Verify webhook signatures in every language; during rotation accept any v1 candidate.
Parse the JSON envelope.
Dedupe on envelope id — a seen id gets a 200 ack and stops.
Route type to the family handler (the receiver examples above).

WhatsApp

Guides

Messaging Controls

Audience & Support Tools

Webhook payload cookbook: one payload per event family

Webhook payload cookbook: one payload per event family

Request shape (all families)

1. Message lifecycle (`message.*`)

2. Voice / call lifecycle (`call.`, `recording.`, `voicemail.*`)

3. Porting (`porting.request.*`)

4. Verify (`verification.*`)

5. CDP events (`cdp.`, `contact.`)

6. Delivery receipts (`submitted_no_receipt` / `expired`)

7. Campaign (`campaign.*`)

8. Flows (`flow.*`)

9. Number lifecycle (`number.*`)

Order: verification before the parser

See also

​Webhook payload cookbook: one payload per event family

​Request shape (all families)

​1. Message lifecycle (message.*)

​2. Voice / call lifecycle (call.*, recording.*, voicemail.*)

​3. Porting (porting.request.*)

​4. Verify (verification.*)

​5. CDP events (cdp.*, contact.*)

​6. Delivery receipts (submitted_no_receipt / expired)

​7. Campaign (campaign.*)

​8. Flows (flow.*)

​9. Number lifecycle (number.*)

​Order: verification before the parser

​See also

Webhook payload cookbook: one payload per event family

Request shape (all families)

1. Message lifecycle (`message.*`)

2. Voice / call lifecycle (`call.`, `recording.`, `voicemail.*`)

3. Porting (`porting.request.*`)

4. Verify (`verification.*`)

5. CDP events (`cdp.`, `contact.`)

6. Delivery receipts (`submitted_no_receipt` / `expired`)

7. Campaign (`campaign.*`)

8. Flows (`flow.*`)

9. Number lifecycle (`number.*`)

Order: verification before the parser

See also