API reference · Webhooks
Change a webhook destination, or pause or resume it
/v1/webhooks/{webhook_id}- TypeScript
client.webhooks.update()- Python
client.webhooks.update()- CLI
hayonix webhooks update
Fields you omit are left as they are. Pausing gives up its pending deliveries (redeliver them after resuming); resuming clears the failure streak. Changes apply to events from then on.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the webhook:update 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 -X PATCH "$API_BASE_URL/webhooks/whk_01jc5zq4m8k3v6x9t2w7r0b1e4" \
-H "Authorization: Bearer $API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "active"
}'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_
Body
JSON (application/json): UpdateWebhookRequest.
urlstringWhere events are POSTed: an https URL (plain http is accepted only by development deployments). Addresses that resolve to loopback, private, link-local or metadata networks are refused when delivering.
1–2048 characters
descriptionstringFree-text description
up to 500 characters
event_typesarray of stringEvent types to receive, or `["*"]` for every type (GET /v1/webhooks/event-types lists them). Organization events (billing) need `org_events: true`.
1–64 items
org_eventsbooleanAlso receive organization events (billing). Turning it on needs billing:read.
statusstring`paused` stops sending (pending deliveries are given up; redeliver them after resuming); `active` resumes and clears the failure streak.
One of
activepaused
Response
200 Webhook — The updated 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). |
409 | conflict_error | The resource's current state does not allow this. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |