Skip to main content

​
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

  1. You register a webhook endpoint URL in the Orbit dashboard or via the API
  2. When an event occurs, Orbit sends an HTTP POST with the event payload to your URL
  3. Your server responds with a 2xx status code to acknowledge receipt
  4. If delivery fails, Orbit retries with exponential backoff

​
Register a Webhook

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

​
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 this schedule:
AttemptDelay
11 minute
25 minutes
330 minutes
42 hours
58 hours
624 hours
After all retries are exhausted, the event is moved to a dead letter queue. You can replay failed events from the dashboard under Webhooks > Failed Deliveries.

​
Managing Webhooks

List your registered webhooks: 
curl https://orbit-api.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..."
Delete a webhook: 
curl -X DELETE https://orbit-api.devotel.io/api/v1/webhooks/wh_abc123 \
  -H "X-API-Key: dv_live_sk_..."

​
Next Steps