Webhooks
Signed HTTPS notifications for platform events: endpoints, deliveries, test events, redelivery and secret rotation.
📄️ The customer-visible event catalog (types, versions, descriptions)
**Access:** API key scope `webhooks:read` on an inference or a management key, or `webhooks:write` on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ List webhook endpoints
**Access:** API key scope `webhooks:read` on an inference or a management key, or `webhooks:write` on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ Register an HTTPS endpoint; the signing secret is returned once
At most 10 endpoints per organization by default (your platform operator sets the limit); the next create answers 409 `webhook_limit` with `details.limit`. The signing secret is in this response only. This call takes no `Idempotency-Key`: if you lost the response, list your webhooks, find the endpoint and rotate its secret with `expire_previous_now: true`.
📄️ Get a webhook endpoint
**Access:** API key scope `webhooks:read` on an inference or a management key, or `webhooks:write` on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ Change a webhook endpoint (URL, events, versions, on/off)
`enabled: true` clears `disabled_reason` / `disabled_at` and restarts the auto-disable rule; deliveries dropped while disabled are not replayed automatically (use `:redeliver`).
📄️ Delete the endpoint; pending deliveries are dropped and its secrets destroyed
**Access:** API key scope `webhooks:write` on a **management** key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ Issue a new signing secret; the previous one keeps signing for 24 h
At most two secrets are live. While the previous secret is still in its 24-hour overlap the call answers 409 `secret_rotation_in_progress` (`details.previous_secret_expires_at`), unless you send `expire_previous_now: true`: the older secret is then destroyed at once and the current one becomes the previous one (the way back after a lost rotation response). No `Idempotency-Key` replay: secrets are never stored in a replayable form.
📄️ Send a signed `integrations.webhook.test` event through the normal delivery path
Sends a fixed test payload (none of your data), signed and recorded like every delivery (`is_test: true`). It works on a disabled endpoint, so you can check a fix before you turn the endpoint back on, and it never counts towards automatic disabling. At most 10 test events per endpoint per hour.
📄️ Delivery history (30 days); response bodies are never stored
**Access:** API key scope `webhooks:read` on an inference or a management key, or `webhooks:write` on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ Get a delivery
**Access:** API key scope `webhooks:read` on an inference or a management key, or `webhooks:write` on a management key; portal users: organization admins and owners; refused for an API key limited to a list of knowledge bases (403 `kb_not_in_allowlist`).
📄️ Deliver the same event again (same event id) as a new delivery
Only for a `succeeded` or `dropped` delivery whose event is still in the 30-day event store and an endpoint that is enabled now; otherwise 409 `redelivery_unavailable`. The new delivery carries `redelivery_of`. ≤ 60 redeliveries per endpoint per hour.