Webhook Events
Orbit emits events across messaging, voice, agents, flows, and account activity. Subscribe to specific events when registering a webhook, or use * to receive all events.
Events marked Active are dispatched by the webhook delivery system today.
Events marked Planned are defined in the schema but not yet emitted — they will be enabled in upcoming releases.
Message Events
Fired for SMS, WhatsApp, RCS, Viber, and Email messages.
| Event | Status | Description |
|---|
message.created | Planned | Message accepted and queued for delivery |
message.sending | Planned | Message is being transmitted to the carrier/provider |
message.sent | Active | Message handed off to the carrier/provider |
message.delivered | Active | Message confirmed delivered to the recipient |
message.failed | Active | Message delivery failed |
message.undelivered | Planned | Message could not be delivered after retries |
message.received | Planned | Inbound message received from a user |
Example: message.delivered
{
"id": "evt_msg_001",
"type": "message.delivered",
"created_at": "2026-03-08T12:00:00Z",
"data": {
"message_id": "msg_abc123",
"channel": "sms",
"from": "+18005551234",
"to": "+1415555****",
"status": "delivered",
"delivered_at": "2026-03-08T12:00:01Z",
"segments": 1
}
}
| Event | Status | Description |
|---|
contact.created | Active | A new contact was created |
contact.updated | Active | An existing contact was modified |
contact.deleted | Active | A contact was removed |
Campaign Events
| Event | Status | Description |
|---|
campaign.started | Active | Campaign execution began |
campaign.completed | Active | Campaign finished sending to all recipients |
campaign.failed | Planned | Campaign execution failed |
Voice Events
| Event | Status | Description |
|---|
call.initiated | Planned | Outbound call placed |
call.ringing | Planned | Destination is ringing |
call.answered | Planned | Call was answered |
call.completed | Planned | Call ended normally |
call.failed | Planned | Call failed to connect |
call.recording_ready | Planned | Call recording is available for download |
Example: call.completed
{
"id": "evt_call_001",
"type": "call.completed",
"created_at": "2026-03-08T12:05:00Z",
"data": {
"call_id": "call_xyz789",
"from": "+18005551234",
"to": "+1415555****",
"duration_seconds": 142,
"status": "completed",
"recording_url": "https://orbit-api.devotel.io/api/v1/recordings/rec_abc123"
}
}
Agent Events
| Event | Status | Description |
|---|
agent.conversation_started | Planned | Agent began a new conversation |
agent.conversation_ended | Planned | Agent conversation completed |
agent.handoff_requested | Planned | Agent requested transfer to a human |
agent.tool_called | Planned | Agent invoked a tool during conversation |
agent.error | Planned | Agent encountered an error |
Flow Events
| Event | Status | Description |
|---|
flow.execution_started | Planned | Flow execution began |
flow.execution_completed | Planned | Flow completed all nodes |
flow.execution_failed | Planned | Flow execution failed at a node |
flow.node_executed | Planned | A specific node completed execution |
Verify Events
| Event | Status | Description |
|---|
verify.started | Planned | Verification code sent |
verify.approved | Planned | Code verified successfully |
verify.failed | Planned | Incorrect code submitted |
verify.expired | Planned | Code expired |
Account Events
| Event | Status | Description |
|---|
number.purchased | Planned | New phone number purchased |
number.released | Planned | Phone number released |
account.balance_low | Planned | Account balance below threshold |
Filtering Events
When creating a webhook, specify which events to receive:
curl -X POST https://orbit-api.devotel.io/api/v1/webhooks \
-H "X-API-Key: dv_live_sk_..." \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/webhooks/orbit",
"events": ["message.delivered", "message.failed", "call.completed"]
}'
"events": ["*"] to subscribe to all event types.
