Webhooks

Orbit webhooks deliver real-time HTTP POST notifications to your server whenever events occur — message delivered, call completed, agent conversation ended, and more. Use webhooks to keep your systems in sync without polling.

How It Works

You register a webhook endpoint URL in the Orbit dashboard or via the API
When an event occurs, Orbit sends an HTTP POST with the event payload to your URL
Your server responds with a 2xx status code to acknowledge receipt
If delivery fails, Orbit retries on a fixed schedule (see Retry Schedule)

Register a Webhook

curl -X POST https://api.orbit.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"],
    "secret": "whsec_your_signing_secret"
  }'

Event Payload Format

Every webhook delivery follows a consistent envelope:

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

Terminal-failure deliveries (message.failed) additionally include optional error_code and error_message fields carrying the provider’s failure reason. They appear only when the message has a captured provider error and are absent otherwise. See the webhook events reference for the full per-event payload shapes.

Delivery Guarantees

At-least-once delivery — events may be delivered more than once; use id for deduplication
Ordered by event time — events are sent in chronological order, but network conditions may cause out-of-order delivery
30-second timeout — your endpoint must respond within 30 seconds

Retry Schedule

If your endpoint returns a non-2xx response or times out, Orbit retries on a fixed schedule. Each event gets one initial delivery plus 6 retries (7 attempts total). Each retry delay carries +0–20% jitter (delays run up to 20% longer than the nominal schedule, never shorter):

Retry	Delay before retry	Elapsed since first attempt
1	1 minute	~1 minute
2	5 minutes	~6 minutes
3	30 minutes	~36 minutes
4	2 hours	~2.6 hours
5	8 hours	~10.6 hours
6	24 hours	~34.6 hours

After the 7th attempt fails, the event is moved to a dead letter queue — roughly 34.6 hours after the first attempt. Size your delivery-expiry, replay, and idempotency-key retention windows accordingly: a failing endpoint receives retries for around a day and a half before the event is dead-lettered, so persist seen event id values for at least 3 days to cover the full retry window plus the dead-letter replay window. You can replay failed events from the dashboard under Webhooks > Failed Deliveries.

Managing Webhooks

List your registered webhooks:

curl https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..."

Delete a webhook:

curl -X DELETE https://api.orbit.devotel.io/api/v1/webhooks/wh_abc123 \
  -H "X-API-Key: dv_live_sk_..."

Next Steps

Event Types — full list of available events
Security — verify webhook signatures

Wallet top-up currency conversion Webhook Events

⌘I

Getting Started

Channels

AI Agents

Flows

Numbers & Verify

Concepts

Billing

Webhooks

Compliance

Legal

Changelog

Webhooks Overview

Webhooks

How It Works

Register a Webhook

Event Payload Format

Delivery Guarantees

Retry Schedule

Managing Webhooks

Next Steps

​Webhooks

​How It Works

​Register a Webhook

​Event Payload Format

​Delivery Guarantees

​Retry Schedule

​Managing Webhooks

​Next Steps

Webhooks

How It Works

Register a Webhook

Event Payload Format

Delivery Guarantees

Retry Schedule

Managing Webhooks

Next Steps