REST API Reference v2.1 — Webhooks
GET /webhooks
Returns all webhook subscriptions for the authenticated account.
Parameters
| Name | Type | Description |
|---|---|---|
| status | string | Filter by status: active, paused, or disabled. Default: all. |
| page | integer | Page number (default: 1) |
| limit | integer | Results per page (default: 20, max: 50) |
Response
{
"data": [
{
"id": "whk_abc123",
"url": "https://yourapp.com/hooks/receiver",
"events": ["user.created", "invoice.paid"],
"status": "active",
"created_at": "2025-01-15T08:30:00Z",
"last_delivery_at": "2025-01-20T14:22:11Z"
}
],
"pagination": {
"page": 1,
"limit": 20,
"total": 3
}
}
POST /webhooks
Creates a new webhook subscription. Requires webhooks:write scope.
Request Body
| Field | Type | Required | Description |
|---|---|---|---|
| url | string | Yes | HTTPS endpoint URL that will receive webhook deliveries. |
| events | array | Yes | List of event types to subscribe to. Use ["*"] for all events. |
| secret | string | No | Signing secret for HMAC-SHA256 signature verification. Auto-generated if omitted. |
| description | string | No | Human-readable description of the webhook's purpose. |
curl -X POST https://api.example.com/webhooks \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"url": "https://yourapp.com/hooks/receiver",
"events": ["user.created", "user.deleted"],
"description": "User lifecycle events"
}'
GET /webhooks/:id/deliveries
Returns the delivery history for a specific webhook. Useful for debugging failed deliveries and monitoring webhook health.
Parameters
| Name | Type | Description |
|---|---|---|
| status | string | Filter by delivery status: success, failed, pending. |
| since | string | ISO 8601 timestamp. Only return deliveries after this time. |
| limit | integer | Results per page (default: 20, max: 100) |
Response
{
"data": [
{
"id": "dlv_xyz789",
"event_type": "user.created",
"status": "success",
"http_status": 200,
"response_time_ms": 142,
"delivered_at": "2025-01-20T14:22:11Z",
"next_retry_at": null
},
{
"id": "dlv_xyz790",
"event_type": "invoice.paid",
"status": "failed",
"http_status": 503,
"response_time_ms": 30012,
"delivered_at": "2025-01-20T15:01:03Z",
"next_retry_at": "2025-01-20T16:01:03Z"
}
]
}
Failed deliveries are retried with exponential backoff: 1 minute, 5 minutes, 30 minutes, 2 hours, 24 hours. After 5 failed attempts, the webhook is automatically paused and a webhook.paused notification is sent to your account email.
Peer-reviewed and accepted for publication. Supplementary data available via linked endpoints.