Webhook Events

Complete reference of all Orbit webhook event types

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": "[phone]",
    "to": "+1415555****",
    "status": "delivered",
    "delivered_at": "2026-03-08T12:00:01Z",
    "segments": 1
  }
}

Contact Events

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": "[phone]",
    "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"]
  }'

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