API reference · Webhooks
Get a webhook destination
/v1/webhooks/{webhook_id}- TypeScript
client.webhooks.get()- Python
client.webhooks.get()- CLI
hayonix webhooks show
Returns the destination with its delivery health; the signing secret is 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/whk_01jc5zq4m8k3v6x9t2w7r0b1e4" \
-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. |
Path parameters
webhook_idstringrequiredID of the webhook
ID with prefix whk_
Response
200 Webhook — The destination
objectstringrequiredAlways `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)
Example response
{
"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"
}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. |
404 | not_found_error | No such resource in this project (an ID from another project is answered the same way). |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |