> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orbit.devotel.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Receive real-time event notifications from Orbit via webhooks

# 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 on a fixed schedule (see [Retry Schedule](#retry-schedule))

## Register a Webhook

```bash theme={null}
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:

```json theme={null}
{
  "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](/reference/webhook-events) 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:

```bash theme={null}
curl https://api.orbit.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_..."
```

Delete a webhook:

```bash theme={null}
curl -X DELETE https://api.orbit.devotel.io/api/v1/webhooks/wh_abc123 \
  -H "X-API-Key: dv_live_sk_..."
```

## Next Steps

* [Event Types](/webhooks/events) — full list of available events
* [Security](/webhooks/security) — verify webhook signatures