> For the complete documentation index, see [llms.txt](https://help.cerby.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications.md). # Explore webhook notifications Cerby's webhook notification service sends a signed HTTP request to a URL you configure each time an account or automation event occurs in your workspace. Webhooks let you push Cerby events into external systems — audit pipelines, ticketing tools, SIEM platforms, or custom automation — without polling the Cerby API. Each request carries a cryptographic signature so your receiver can confirm the payload came from Cerby and was not modified in transit. Cerby retries failed deliveries automatically, so a brief outage on your endpoint does not cause missed events. {% hint style="info" %} **Who can use this feature?** * Workspace **Owners**, **Super Admins**, and **Admins** * Supported using the **Cerby web app** and the Cerby API {% endhint %} ## Key benefits The following are the main benefits of webhook notifications: * **Real-time event delivery:** Receive notifications the moment an event occurs in Cerby, rather than polling the API on a schedule. Your systems stay current without building or maintaining a polling loop. * **Tamper-evident signing:** Every request is signed with Ed25519 or HMAC-SHA256. Your receiver can verify cryptographically that each payload came from Cerby and arrived unmodified. * **Built-in reliability:** Cerby retries failed deliveries up to six times over a 24-hour window with exponential backoff. A transient network issue does not cause a missed event. * **Programmatic error handling:** Automation failure events carry a machine-readable error code and remediation category, so your integration can route or act on failures without parsing human-readable messages. * **Flexible subscriptions:** Subscribe to individual event types or use a Quick Start bundle to cover common scenarios in one step. Each webhook can have a different subscription set. ## Key features ### Event subscriptions Cerby sends events across six categories: account lifecycle, account credentials, account access, account authentication, automation outcomes, and automation completions. When you create a webhook, you subscribe to the event types you want to receive. Subscriptions match exact event type strings — there are no wildcards. Automation outcomes covers the two catch-all events: `automation.succeeded`, which fires for every completed automation job, and `automation.failed`, which fires for every failed automation job. `automation.failed` is a single subscribable type that covers all automation failure scenarios. The specific failure is identified by an `error.code` field in the payload, paired with a `user_action` category your integration can act on programmatically. Automation completions covers the six action-specific success events (for example, `automation.password.rotated`), which co-fire alongside `automation.succeeded` for the same job. {% hint style="info" %} Several event types are provisional and may not be delivered in all cases. The catalogue will be finalized before the GA release. For the full event list with provisional labels, refer to [Implement a webhook receiver](https://github.com/cerbyinc/help-center/tree/main/extending_cerby/public-api/implement-a-webhook-receiver.md). {% endhint %} ### Signed delivery Every webhook request is signed with the algorithm you choose when you create the webhook. Your receiver fetches Cerby's public key (Ed25519) or shared secret (HMAC-SHA256) from the Cerby API and uses it to verify the signature on each incoming request. Cerby includes the signing key ID and a timestamp in each request so your receiver can reject replayed requests and handle key rotations without downtime. When you rotate a signing key, Cerby dual-signs every request with both the old and new keys for 24 hours. Your receiver can update its stored key at any point in that window without dropping valid deliveries. ### Reliable delivery Cerby guarantees at-least-once delivery. If your endpoint is unavailable or returns a retryable error, Cerby retries the delivery automatically. Each delivery carries a stable identifier that is constant across all retry attempts, so your receiver can deduplicate safely. Permanent errors — such as an endpoint returning a 401 or 404 — cause Cerby to stop retrying immediately rather than exhausting the retry budget on a failure that will not self-heal. ## Supported platforms * **Cerby web app** — Create and manage webhook endpoints in workspace settings. * **Cerby API** — Read delivery history and manage webhooks programmatically. ## How to get started ### For admins To start receiving Cerby events, complete the following steps: 1. Create a webhook endpoint in your workspace settings. Specify the HTTPS URL, select the event types to subscribe to, and choose a signing algorithm. 2. Copy the signing key material when it is displayed. Cerby shows it only once. 3. Share the signing key and the endpoint URL with the developer who will implement the receiver. For detailed steps, refer to [Create a webhook](/setup-and-admin/workspace-settings/webhooks/create-a-webhook.md). ### For developers To implement a webhook receiver, complete the following steps: 1. Set up an HTTPS endpoint that can accept POST requests from Cerby. 2. Implement signature verification using the reference verifier for your language. 3. Deduplicate incoming requests using the `X-Cerby-Delivery` header. 4. Process events based on `event_type` and, for failure events, `error.code`. For the envelope schema, header reference, verifier code, and error code catalogue, refer to [Implement a webhook receiver](https://github.com/cerbyinc/help-center/tree/main/extending_cerby/public-api/implement-a-webhook-receiver.md). ## Current release limitations The following limitations apply to webhooks in this release: * **`account.deleted` not delivered:** The event type is available for subscription but Cerby does not deliver it in this release. To audit account deletions, use the Cerby API or the workspace audit log. * **Canada region not supported:** Webhooks are not available for Canada-resident workspaces (`ca-central-1`) in this release. * **Standalone events:** Events are not linked to related events. For example, an `automation.failed` event and a later success carry no shared correlation identifier. The `trace_id` and `correlation_id` fields are reserved and always null in this release. ## Related articles **Setup guides:** * [Create a webhook](/setup-and-admin/workspace-settings/webhooks/create-a-webhook.md) **Developer reference:** * [Implement a webhook receiver](https://github.com/cerbyinc/help-center/tree/main/extending_cerby/public-api/implement-a-webhook-receiver.md) **Troubleshooting:** * [Troubleshooting: Webhook deliveries failing](https://github.com/cerbyinc/help-center/tree/main/tips_and_troubleshooting/troubleshooting/webhooks/troubleshooting-webhook-deliveries-failing.md) --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.