API Reference
Webhooks
Register, update, and manage webhook subscriptions.
POST /api/v1/webhooks
Register a webhook.
Request
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS endpoint URL |
events | string[] | Yes | Events to subscribe to (see event list) |
secret | string | No | Shared secret for HMAC-SHA256 signing |
Response 201
The created webhook object.
GET /api/v1/webhooks
List registered webhooks.
PUT /api/v1/webhooks/:id
Update a webhook's URL, events, or secret.
DELETE /api/v1/webhooks/:id
Delete a webhook. Stops all deliveries immediately.
PATCH /api/v1/webhooks/:id/toggle
Toggle enabled/disabled state.
Delivery format
All webhook deliveries are POST requests with Content-Type: application/json.
Headers
| Header | Description |
|---|---|
Content-Type | application/json |
X-Webhook-Signature | HMAC-SHA256 hex digest (present if secret was set) |
Body
{
"event": "message.received",
"timestamp": "2025-01-15T10:30:00Z",
"data": { }
}The data shape depends on the event type.
message.* events data
{
"id": "msg_abc123",
"to": "+15551234567",
"from": "+15559876543",
"body": "Message text",
"status": "delivered",
"conversationId": "conv_123"
}relay.* events data
{
"id": "relay_001",
"name": "Office Mac Mini",
"status": "online"
}Retries
Non-2xx responses trigger retries with exponential backoff. After repeated failures, the delivery is marked as failed.