Webhooks API
All webhook endpoints require the webhooks:manage scope and ADMIN role on the workspace.
Create a webhook endpoint
POST /v1/webhooks
| Field | Type | Required | Description |
|---|---|---|---|
url | string | Yes | HTTPS endpoint URL (must be publicly accessible — localhost and private IPs are rejected) |
events | string[] | Yes | Events to subscribe to |
workspaceId | string | Yes | Workspace to scope the webhook to |
The response includes a secret field (prefixed with whsec_). This is shown only once — store it securely for signature verification.
List webhook endpoints
GET /v1/webhooks?workspaceId=ws_123
| Parameter | Type | Required | Description |
|---|---|---|---|
workspaceId | string | Yes | Workspace to list webhooks for |
Returns all active endpoints. Secrets are never included.
Get a webhook endpoint
GET /v1/webhooks/:id
List deliveries
GET /v1/webhooks/:id/deliveries
Returns delivery history with status, HTTP status code, attempt count, and error details. Supports cursor pagination.
Retry a failed delivery
POST /v1/webhooks/:id/deliveries/:deliveryId/retry
Re-queues an exhausted delivery for immediate retry.
Regenerate signing secret
POST /v1/webhooks/:id/regenerate-secret
Generates a new whsec_ signing secret. The old secret is immediately invalidated. Update your receiver before regenerating.
Delete a webhook endpoint
DELETE /v1/webhooks/:id
Returns 200 OK with the deleted endpoint ID:
{ "data": { "id": "whk_abc123", "deletedAt": "2026-03-30T10:00:00.000Z" } }
The endpoint stops receiving events immediately.