Webhook Events Reference

Complete reference of every webhook event type Orbit emits, with full payload examples for each.

Event Envelope

Every webhook delivery wraps the event in a standard envelope:

{
  "id": "evt_abc123",
  "type": "message.delivered",
  "created_at": "2026-03-08T12:00:00Z",
  "data": { ... }
}

Field	Type	Description
`id`	string	Unique event ID (idempotency key)
`type`	string	Event type identifier
`created_at`	string	ISO 8601 timestamp
`data`	object	Event-specific payload

Message Events

`message.created`

Fired when a message is accepted and queued for delivery.

{
  "id": "evt_msg_001",
  "type": "message.created",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+18005551234",
    "to": "+14155552671",
    "body": "Your verification code is 123456",
    "status": "queued",
    "segments": 1,
    "metadata": { "campaign": "onboarding" }
  }
}

`message.sent`

Fired when a message is handed off to the carrier or provider.

{
  "id": "evt_msg_002",
  "type": "message.sent",
  "created_at": "2026-03-08T12:00:01Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "sent",
    "provider_id": "prov_sms_xyz"
  }
}

`message.delivered`

Fired when delivery is confirmed by the carrier.

{
  "id": "evt_msg_003",
  "type": "message.delivered",
  "created_at": "2026-03-08T12:00:03Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "delivered",
    "delivered_at": "2026-03-08T12:00:03Z",
    "segments": 1
  }
}

`message.failed`

Fired when message delivery fails.

{
  "id": "evt_msg_004",
  "type": "message.failed",
  "created_at": "2026-03-08T12:00:05Z",
  "data": {
    "message_id": "msg_abc123",
    "channel": "sms",
    "from": "+18005551234",
    "to": "+14155552671",
    "status": "failed",
    "error_code": "INVALID_RECIPIENT",
    "error_message": "The destination number is not reachable"
  }
}

`message.received`

Fired when an inbound message is received from a user.

{
  "id": "evt_msg_005",
  "type": "message.received",
  "created_at": "2026-03-08T12:05:00Z",
  "data": {
    "message_id": "msg_inb_456",
    "channel": "sms",
    "from": "+14155552671",
    "to": "+18005551234",
    "body": "What is my order status?",
    "number_id": "num_abc123"
  }
}

Contact Events

`contact.created`

{
  "id": "evt_con_001",
  "type": "contact.created",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "contact_id": "con_abc123",
    "first_name": "Jane",
    "last_name": "Doe",
    "phone": "+14155552671",
    "email": "jane@example.com",
    "tags": ["vip", "enterprise"]
  }
}

`contact.updated`

{
  "id": "evt_con_002",
  "type": "contact.updated",
  "created_at": "2026-03-08T12:10:00Z",
  "data": {
    "contact_id": "con_abc123",
    "changes": {
      "tags": { "old": ["vip"], "new": ["vip", "enterprise"] }
    },
    "updated_at": "2026-03-08T12:10:00Z"
  }
}

`contact.deleted`

{
  "id": "evt_con_003",
  "type": "contact.deleted",
  "created_at": "2026-03-08T12:15:00Z",
  "data": {
    "contact_id": "con_abc123",
    "deleted_at": "2026-03-08T12:15:00Z"
  }
}

Campaign Events

`campaign.started`

{
  "id": "evt_camp_001",
  "type": "campaign.started",
  "created_at": "2026-03-08T10:00:00Z",
  "data": {
    "campaign_id": "camp_abc123",
    "name": "March Newsletter",
    "channel": "sms",
    "total_recipients": 5420,
    "started_at": "2026-03-08T10:00:00Z"
  }
}

`campaign.completed`

{
  "id": "evt_camp_002",
  "type": "campaign.completed",
  "created_at": "2026-03-08T10:45:00Z",
  "data": {
    "campaign_id": "camp_abc123",
    "name": "March Newsletter",
    "total_recipients": 5420,
    "delivered": 5312,
    "failed": 108,
    "completed_at": "2026-03-08T10:45:00Z"
  }
}

`campaign.failed`

{
  "id": "evt_camp_003",
  "type": "campaign.failed",
  "created_at": "2026-03-08T10:05:00Z",
  "data": {
    "campaign_id": "camp_def456",
    "name": "Flash Sale",
    "error": "INSUFFICIENT_CREDITS",
    "sent_before_failure": 1200,
    "remaining": 3800,
    "failed_at": "2026-03-08T10:05:00Z"
  }
}

Voice Events

`call.initiated`

{
  "id": "evt_call_001",
  "type": "call.initiated",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "call_id": "call_abc123",
    "from": "+18005551234",
    "to": "+14155552671",
    "direction": "outbound",
    "agent_id": "agt_support"
  }
}

`call.answered`

{
  "id": "evt_call_002",
  "type": "call.answered",
  "created_at": "2026-03-08T12:00:08Z",
  "data": {
    "call_id": "call_abc123",
    "answered_at": "2026-03-08T12:00:08Z"
  }
}

`call.completed`

{
  "id": "evt_call_003",
  "type": "call.completed",
  "created_at": "2026-03-08T12:05:00Z",
  "data": {
    "call_id": "call_abc123",
    "from": "+18005551234",
    "to": "+14155552671",
    "duration_seconds": 292,
    "status": "completed",
    "recording_url": "https://storage.devotel.io/recordings/call_abc123.wav",
    "ended_at": "2026-03-08T12:05:00Z"
  }
}

`call.failed`

{
  "id": "evt_call_004",
  "type": "call.failed",
  "created_at": "2026-03-08T12:00:30Z",
  "data": {
    "call_id": "call_def456",
    "from": "+18005551234",
    "to": "+14155559999",
    "error_code": "NO_ANSWER",
    "error_message": "Destination did not answer within 30 seconds"
  }
}

`call.recording_ready`

{
  "id": "evt_call_005",
  "type": "call.recording_ready",
  "created_at": "2026-03-08T12:06:00Z",
  "data": {
    "call_id": "call_abc123",
    "recording_id": "rec_abc123",
    "duration_seconds": 292,
    "file_size_bytes": 4680192,
    "recording_url": "https://storage.devotel.io/recordings/rec_abc123.wav",
    "transcription_url": "https://storage.devotel.io/transcriptions/rec_abc123.json"
  }
}

Agent Events

`agent.conversation_started`

{
  "id": "evt_agt_001",
  "type": "agent.conversation_started",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_001",
    "channel": "whatsapp",
    "contact_id": "con_xyz789",
    "started_at": "2026-03-08T12:00:00Z"
  }
}

`agent.conversation_ended`

{
  "id": "evt_agt_002",
  "type": "agent.conversation_ended",
  "created_at": "2026-03-08T12:15:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_001",
    "message_count": 12,
    "duration_seconds": 900,
    "resolution": "resolved",
    "ended_at": "2026-03-08T12:15:00Z"
  }
}

`agent.handoff_requested`

{
  "id": "evt_agt_003",
  "type": "agent.handoff_requested",
  "created_at": "2026-03-08T12:10:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_001",
    "reason": "Customer requested to speak with a human agent",
    "priority": "high"
  }
}

`agent.tool_called`

{
  "id": "evt_agt_004",
  "type": "agent.tool_called",
  "created_at": "2026-03-08T12:02:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_001",
    "tool_name": "lookup_order",
    "input": { "order_id": "ORD-12345" },
    "output": { "status": "shipped", "carrier": "FedEx" },
    "latency_ms": 245
  }
}

`agent.error`

{
  "id": "evt_agt_005",
  "type": "agent.error",
  "created_at": "2026-03-08T12:03:00Z",
  "data": {
    "agent_id": "agt_abc123",
    "conversation_id": "conv_001",
    "error_code": "LLM_PROVIDER_ERROR",
    "error_message": "LLM gateway returned 503"
  }
}

Flow Events

`flow.execution_started`

{
  "id": "evt_flow_001",
  "type": "flow.execution_started",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "trigger": "webhook",
    "started_at": "2026-03-08T12:00:00Z"
  }
}

`flow.execution_completed`

{
  "id": "evt_flow_002",
  "type": "flow.execution_completed",
  "created_at": "2026-03-08T12:00:05Z",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_001",
    "nodes_executed": 8,
    "duration_ms": 5200,
    "completed_at": "2026-03-08T12:00:05Z"
  }
}

Verify Events

`verify.approved`

{
  "id": "evt_ver_001",
  "type": "verify.approved",
  "created_at": "2026-03-08T12:01:00Z",
  "data": {
    "verification_id": "ver_abc123",
    "to": "+14155552671",
    "channel": "sms",
    "approved_at": "2026-03-08T12:01:00Z"
  }
}

`verify.failed`

{
  "id": "evt_ver_002",
  "type": "verify.failed",
  "created_at": "2026-03-08T12:01:30Z",
  "data": {
    "verification_id": "ver_def456",
    "to": "+14155552671",
    "channel": "sms",
    "attempts": 3,
    "reason": "max_attempts_exceeded"
  }
}

Account Events

`number.purchased`

{
  "id": "evt_num_001",
  "type": "number.purchased",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "number_id": "num_abc123",
    "number": "+14155550100",
    "country": "US",
    "type": "local",
    "capabilities": ["sms", "voice"]
  }
}

`number.released`

{
  "id": "evt_num_002",
  "type": "number.released",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "number_id": "num_abc123",
    "number": "+14155550100",
    "released_at": "2026-03-08T12:00:00Z"
  }
}

`account.balance_low`

{
  "id": "evt_acct_001",
  "type": "account.balance_low",
  "created_at": "2026-03-08T12:00:00Z",
  "data": {
    "current_balance": 2500,
    "currency": "usd",
    "threshold": 5000,
    "auto_reload_enabled": false
  }
}

Subscribing to Events

curl -X POST https://orbit-api.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "call.completed"],
    "secret": "whsec_your_secret"
  }'

Use "events": ["*"] to subscribe to all event types.

Reference

​Webhook Events Reference

​Event Envelope

​Message Events

​message.created

​message.sent

​message.delivered

​message.failed

​message.received

​Contact Events

​contact.created

​contact.updated

​contact.deleted

​Campaign Events

​campaign.started

​campaign.completed

​campaign.failed

​Voice Events

​call.initiated

​call.answered

​call.completed

​call.failed

​call.recording_ready

​Agent Events

​agent.conversation_started

​agent.conversation_ended

​agent.handoff_requested

​agent.tool_called

​agent.error

​Flow Events

​flow.execution_started

​flow.execution_completed

​Verify Events

​verify.approved

​verify.failed

​Account Events

​number.purchased

​number.released

​account.balance_low

​Subscribing to Events