API reference · Webhooks
Create a webhook destination (its signing secret is returned once)
/v1/webhooks- TypeScript
client.webhooks.create()- Python
client.webhooks.create()- CLI
hayonix webhooks create
Events of the chosen types that happen in this project are POSTed to the URL from now on, signed with the secret in this response, which cannot be read again. Delivery is at least once and in no promised order: deduplicate on the Webhook-Id header. A project can have up to 20 destinations.
Project API key (Authorization: Bearer sk_…), or a console session. Requires the webhook:create 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" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"url": "https://hooks.example.com/platform",
"description": "Ops alerts",
"event_types": [
"pod.stopped",
"pod.host_lost"
],
"org_events": false
}'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. |
Idempotency-Key | no | Makes a retry safe: the same key and request within 24 hours return the original response (see Idempotency). The SDKs send one for you. |
Body
JSON (application/json): CreateWebhookRequest.
urlstringrequiredWhere 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 · default ["*"]
org_eventsbooleanAlso receive organization events (billing: low balance, out of credit, payments, auto-recharge). Needs billing:read.
default false
Response
201 CreatedWebhook — The new destination, with its secret
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)
secretstringrequiredThe signing secret (`whs_…`). Shown only now; store it with your receiver.
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",
"secret": "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. |
409 | conflict_error idempotency_in_progress | A request with the same Idempotency-Key is still running. |
422 | idempotency_error idempotency_key_reused | The Idempotency-Key was used with a different request. |
429 | rate_limit_error rate_limited | Too many requests; retry after retry-after seconds. |