API reference · Webhooks
List the project’s webhook destinations, with their delivery health
/v1/webhooks- TypeScript
client.webhooks.list()- Python
client.webhooks.list()- CLI
hayonix webhooks list
Newest first. Signing secrets are never included.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the webhook:read permission (a key's scope, or a role that includes it).
Examples
The samples read API_KEY and API_BASE_URL from the environment (see Setup). Values are examples.
curl -sS "$API_BASE_URL/webhooks" \
-H "Authorization: Bearer $API_KEY"Request
| Header | Required | Description |
|---|---|---|
Authorization | yes | Bearer and your API key. The key implies its project. |
X-Project-Id | session only | The project to act in, for console sessions. Requests with an API key leave it out. |
Query parameters
limitinteger1–200, default 50
1–200
cursorstring`next_cursor` of the previous page
up to 200 characters
Response
200 a page of results — A page of destinations, newest first
The items of this page.
ShowHide 14 fields of
dataobjectstringrequiredAlways `webhook`: the type of this object
One of
webhookidstringrequiredUnique ID (`whk_…`)
ID with prefix whk_
project_idstringrequiredProject it belongs to
ID with prefix prj_
urlstringrequiredWhere events are POSTed
descriptionstringrequiredFree-text description
event_typesarray of stringrequiredEvent types it receives; `["*"]` means every type
org_eventsbooleanrequiredWhether it also receives organization events (billing)
statusstringrequired`active` (events are delivered) or `paused` (nothing is sent; see `paused`)
One of
activepausedpausedobject | nullrequiredWhy it is paused: by a member (`requested`) or automatically after 20 failed attempts in a row over at least 24 hours (`failing`)
ShowHide 2 fields of
pausedreasonstringrequired`requested` (paused by a member) or `failing` (paused automatically)
One of
requestedfailingatstring (date-time)requiredWhen it was paused (ISO 8601, UTC)
secret_rotated_atstring (date-time) | nullrequiredTime secret rotated (ISO 8601, UTC)
previous_secret_expires_atstring (date-time) | nullrequiredUntil then, deliveries carry a signature with the previous secret as well
healthobjectrequiredRecent delivery results at a glance
ShowHide 8 fields of
healthlast_attempt_atstring (date-time) | nullrequiredTime last attempt (ISO 8601, UTC)
last_success_atstring (date-time) | nullrequiredTime last success (ISO 8601, UTC)
last_failure_atstring (date-time) | nullrequiredTime last failure (ISO 8601, UTC)
consecutive_failuresintegerrequiredFailed attempts in a row across all its deliveries; reset by a successful attempt or by resuming
failing_sincestring (date-time) | nullrequiredStart of the current run of failed attempts (ISO 8601, UTC); null when it is not failing
deliveries_24hintegerrequiredFinished deliveries, last 24 h
failed_24hintegerrequiredFailed deliveries, last 24 h
pendingintegerrequiredDeliveries waiting or retrying
created_atstring (date-time)requiredWhen it was created (ISO 8601, UTC)
updated_atstring (date-time)requiredWhen it last changed (ISO 8601, UTC)
next_cursorstring | nullrequiredPass as `cursor` for the next page; null on the last page.
Example response
{
"data": [
{
"object": "webhook",
"id": "whk_01jc5zq4m8k3v6x9t2w7r0b1e4",
"project_id": "prj_01jc5zq4m8k3v6x9t2w7r0b1e4",
"url": "string",
"description": "string",
"event_types": [
"string"
],
"org_events": true,
"status": "active",
"paused": {
"reason": "requested",
"at": "2026-01-01T00:00:00.000Z"
},
"secret_rotated_at": "2026-01-01T00:00:00.000Z",
"previous_secret_expires_at": "2026-01-01T00:00:00.000Z",
"health": {
"last_attempt_at": "2026-01-01T00:00:00.000Z",
"last_success_at": "2026-01-01T00:00:00.000Z",
"last_failure_at": "2026-01-01T00:00:00.000Z",
"consecutive_failures": 1,
"failing_since": "2026-01-01T00:00:00.000Z",
"deliveries_24h": 1,
"failed_24h": 1,
"pending": 1
},
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"next_cursor": "string"
}Errors
Errors use the standard envelope. What this operation can answer:
| Status | Type | When |
|---|---|---|
400 | invalid_request_error | A parameter or body field is missing or not allowed; param names it. |
401 | authentication_error | The key or session is missing, revoked or expired. |
403 | permission_error | The credential lacks the permission this needs, or the organization is suspended. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |