Skip to main content

​
Webhooks API

Register HTTP endpoints to receive real-time event notifications from Orbit. Webhooks are signed with HMAC-SHA256 and delivered with automatic retries. Base path: /v1/webhooks

​
Create Webhook Endpoint

POST /v1/webhooks Register a new webhook endpoint to receive events.
​
url
string
required
The HTTPS URL where events will be delivered
​
events
string[]
required
Array of event types to subscribe to (e.g., message.delivered, message.failed, call.completed)
​
description
string
Human-readable description for this endpoint
curl -X POST https://orbit-api.devotel.io/api/v1/webhooks \
  -H "X-API-Key: dv_live_sk_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "call.completed"],
    "description": "Production webhook receiver"
  }'

{
  "data": {
    "id": "wh_abc123",
    "url": "https://example.com/webhooks/orbit",
    "events": ["message.delivered", "message.failed", "call.completed"],
    "description": "Production webhook receiver",
    "active": true,
    "signing_secret": "whsec_abc123...",
    "created_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_wh_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}
The signing_secret is only returned once — when the endpoint is created. Store it securely. You’ll need it to verify the X-Devotel-Signature header on incoming webhook deliveries.

​
List Webhook Endpoints

GET /v1/webhooks Retrieve all registered webhook endpoints with cursor-based pagination.
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)

​
Get Webhook Endpoint

GET /v1/webhooks/{id} Retrieve a single webhook endpoint by ID.
​
id
string
required
Webhook endpoint ID (e.g., wh_abc123)

​
Update Webhook Endpoint

PUT /v1/webhooks/{id} Update an endpoint’s URL, subscribed events, active status, or description.
​
id
string
required
Webhook endpoint ID
​
url
string
Updated HTTPS URL
​
events
string[]
Updated event subscriptions (replaces existing list)
​
active
boolean
Set to false to temporarily disable delivery without deleting the endpoint
​
description
string
Updated description

​
Delete Webhook Endpoint

DELETE /v1/webhooks/{id} Permanently remove a webhook endpoint. Pending deliveries are cancelled.
​
id
string
required
Webhook endpoint ID
Response: 204 No Content

​
Test Webhook Endpoint

POST /v1/webhooks/{id}/test Send a test event to a webhook endpoint. The test payload is a webhook.test event with sample data. Use this to verify your endpoint is reachable and processing events correctly.
​
id
string
required
Webhook endpoint ID
curl -X POST https://orbit-api.devotel.io/api/v1/webhooks/wh_abc123/test \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": {
    "success": true,
    "response_status": 200,
    "response_time_ms": 145,
    "delivered_at": "2026-03-08T12:00:00Z"
  },
  "meta": {
    "request_id": "req_test_001",
    "timestamp": "2026-03-08T12:00:00Z"
  }
}

​
List Deliveries

GET /v1/webhooks/{id}/deliveries Retrieve the delivery log for a specific webhook endpoint. Each entry shows the HTTP status, response time, retry count, and whether delivery succeeded.
​
id
string
required
Webhook endpoint ID
​
cursor
string
Cursor for pagination
​
limit
integer
default:"20"
Number of results per page (max 100)
curl "https://orbit-api.devotel.io/api/v1/webhooks/wh_abc123/deliveries?limit=5" \
  -H "X-API-Key: dv_live_sk_your_key_here"

{
  "data": [
    {
      "id": "dlv_001",
      "event_type": "message.delivered",
      "event_id": "evt_abc123",
      "status": "success",
      "http_status": 200,
      "response_time_ms": 92,
      "attempt": 1,
      "delivered_at": "2026-03-08T11:30:00Z"
    },
    {
      "id": "dlv_002",
      "event_type": "message.failed",
      "event_id": "evt_def456",
      "status": "failed",
      "http_status": 500,
      "response_time_ms": 30012,
      "attempt": 6,
      "next_retry_at": null,
      "delivered_at": "2026-03-08T10:00:00Z"
    }
  ],
  "meta": {
    "request_id": "req_dlv_001",
    "timestamp": "2026-03-08T12:00:00Z",
    "pagination": {
      "cursor": "cur_dlv_abc",
      "has_more": true
    }
  }
}

​
Delivery Retry Schedule

Orbit retries failed webhook deliveries on this schedule:
AttemptDelay after previous
1Immediate
21 minute
35 minutes
430 minutes
52 hours
68 hours
724 hours
After all retries are exhausted, the event is moved to a dead letter queue. Events in the DLQ can be viewed in the dashboard.

​
Signature Verification

Every webhook delivery includes an X-Devotel-Signature header containing an HMAC-SHA256 signature. Verify it using your endpoint’s signing_secret: 
const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}
See Webhook Security for full implementation details.