Webhooks

Package webhooks is how your app hears about events: register an endpoint, pick the events, get each one delivered and signed.

webhooks

GET /v1/webhooks/{id}/deliveries

Returns one endpoint's per-attempt delivery log, newest first — the record of what was sent, what the subscriber answered, and how long it took. One event that retried three times appears as three rows sharing a delivery id. It is org-scoped exactly like every other route here: the endpoint lookup only ever finds THIS org's endpoint, so another org's id is a 404 and never a window onto its logs.

POST /v1/webhooks/{id}/secret

Mints a NEW HMAC signing secret for the endpoint and answers the endpoint WITH it — the only other response besides create that ever carries a secret. The old secret stops working the instant this returns: every subsequent delivery signs with the new one, with no overlap window. Call it when the subscriber is ready to swap the value on its side, not before.

POST /v1/webhooks/{id}/test

Sends ONE signed test event to the endpoint right now and answers the outcome inline, so the console can show whether the subscriber is reachable without waiting for real traffic. It takes the same attempt path the bus dispatcher takes — one attempt, 10s timeout, no retry ladder — and records the result in the endpoint's delivery log. It works on a DISABLED endpoint too: validating one you have paused is the whole point.

GET /v1/webhooks/{id}

Returns one of the caller org's webhook endpoints with its 7-day delivery and failure counts, signing secret redacted. An id another org owns reads as not found, so the response cannot confirm that it exists.

PUT /v1/webhooks/{id}

Replaces the editable fields of one of the caller org's endpoints — url, events, status and description — and answers the stored row with its secret redacted. It is a full replace, not a patch: an omitted field is written as its empty value, and an omitted or empty events list resubscribes the endpoint to EVERY event. The signing secret and the creation time are immutable here; rotate the secret with POST /v1/webhooks/{id}/secret.

Request body — application/json (required)

DELETE /v1/webhooks/{id}

Removes one of the caller org's webhook endpoints and answers 204 with no body. Delivery stops immediately and the endpoint's signing secret is gone with it; its recorded delivery history goes too. An id another org owns reads as not found.

GET /v1/webhooks

Returns every webhook endpoint the caller's org has registered, newest first, each with its 7-day delivery and failure counts. Signing secrets are redacted here — a secret leaves the server only on create and on rotate. The listing is physically org-scoped, so another tenant's endpoints are not reachable from this route at all.

POST /v1/webhooks

Registers a new webhook subscription for the caller's org and answers 201 with the endpoint INCLUDING its freshly minted signing secret. This is one of only two responses that ever carry that secret (the other is rotate) — store it now, because no later read returns it. The org is stamped by the server from the validated principal, so a body can never register an endpoint in another tenant.

Request body — application/json (required)

---

All Hanzo APIs · Interactive reference