Skip to content
Hayonix

API reference · Webhooks

Create a webhook destination (its signing secret is returned once)

POST/v1/webhooks
API keywebhook:createProjectIdempotency-Key
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

Headers
HeaderRequiredDescription
AuthorizationyesBearer and your API key. The key implies its project.
X-Project-Idsession onlyThe project to act in, for console sessions. Requests with an API key leave it out.
Idempotency-KeynoMakes 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.

  • urlstringrequired

    Where 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

  • descriptionstring

    Free-text description

    up to 500 characters

  • event_typesarray of string

    Event 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_eventsboolean

    Also 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

  • objectstringrequired

    Always `webhook`: the type of this object

    One ofwebhook

  • idstringrequired

    Unique ID (`whk_…`)

    ID with prefix whk_

  • project_idstringrequired

    Project it belongs to

    ID with prefix prj_

  • urlstringrequired

    Where events are POSTed

  • descriptionstringrequired

    Free-text description

  • event_typesarray of stringrequired

    Event types it receives; `["*"]` means every type

  • org_eventsbooleanrequired

    Whether it also receives organization events (billing)

  • statusstringrequired

    `active` (events are delivered) or `paused` (nothing is sent; see `paused`)

    One ofactivepaused

  • pausedobject | nullrequired

    Why it is paused: by a member (`requested`) or automatically after 20 failed attempts in a row over at least 24 hours (`failing`)

    Show 2 fields of paused
    • reasonstringrequired

      `requested` (paused by a member) or `failing` (paused automatically)

      One ofrequestedfailing

    • atstring (date-time)required

      When it was paused (ISO 8601, UTC)

  • secret_rotated_atstring (date-time) | nullrequired

    Time secret rotated (ISO 8601, UTC)

  • previous_secret_expires_atstring (date-time) | nullrequired

    Until then, deliveries carry a signature with the previous secret as well

  • healthobjectrequired

    Recent delivery results at a glance

    Show 8 fields of health
    • last_attempt_atstring (date-time) | nullrequired

      Time last attempt (ISO 8601, UTC)

    • last_success_atstring (date-time) | nullrequired

      Time last success (ISO 8601, UTC)

    • last_failure_atstring (date-time) | nullrequired

      Time last failure (ISO 8601, UTC)

    • consecutive_failuresintegerrequired

      Failed attempts in a row across all its deliveries; reset by a successful attempt or by resuming

    • failing_sincestring (date-time) | nullrequired

      Start of the current run of failed attempts (ISO 8601, UTC); null when it is not failing

    • deliveries_24hintegerrequired

      Finished deliveries, last 24 h

    • failed_24hintegerrequired

      Failed deliveries, last 24 h

    • pendingintegerrequired

      Deliveries waiting or retrying

  • created_atstring (date-time)required

    When it was created (ISO 8601, UTC)

  • updated_atstring (date-time)required

    When it last changed (ISO 8601, UTC)

  • secretstringrequired

    The signing secret (`whs_…`). Shown only now; store it with your receiver.

Example response
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:

Errors
StatusTypeWhen
400invalid_request_errorA parameter or body field is missing or not allowed; param names it.
401authentication_errorThe key or session is missing, revoked or expired.
403permission_errorThe credential lacks the permission this needs, or the organization is suspended.
409conflict_error idempotency_in_progressA request with the same Idempotency-Key is still running.
422idempotency_error idempotency_key_reusedThe Idempotency-Key was used with a different request.
429rate_limit_error rate_limitedToo many requests; retry after retry-after seconds.