> 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

This article describes Cerby's webhook notification service, how event delivery works, and the event types available for subscription.

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 such as 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 makes up to six delivery attempts over a 24-hour window with exponential backoff. A transient network issue does not cause a missed event.
* **Programmatic error handling:** 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 apply a preset to cover common scenarios in one step. Each webhook can have a different subscription set.

## Key features

### Event subscriptions

Cerby sends events across the following domains:

* **Account lifecycle:** Accounts added, disabled, or re-enabled, vaults assigned to an account, and changes to the workspace security policy.
* **Account credentials:** Credentials updated or rotated, rotation failures, and credential breach detections.
* **Account access:** Accounts shared with teams or users, role changes, revocations, and ownership transfers.
* **Account authentication:** Login failures, MFA turned on or off, MFA setup failures, session terminations, and trusted device approvals.
* **Account vault transfers:** Vault transfer requests, approvals, rejections, and cancellations.
* **Automation outcomes:** Two catch-all events that fire for every automation that succeeds or fails.
* **Automation completions:** Action-specific success events, for example a password rotation or a user provisioning run.

When you create a webhook, you subscribe to the event types you want to receive. Subscriptions match exact event type strings, and Cerby supports 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 action-specific success events, which fire alongside `automation.succeeded` for the same job.

For the full event list with payload fields for each type, refer to [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver).

### Signed delivery

Every webhook request is signed with the algorithm you choose when you create the webhook. For Ed25519, your receiver fetches Cerby's public key from the Cerby API and uses it to verify the signature on each incoming request. For HMAC-SHA256, Cerby displays the shared secret once when you create the webhook or rotate the key, and you store it yourself. Cerby cannot recover it afterward.

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 resolve itself.

## Supported platforms

Cerby supports webhooks on the following 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 and alert events, `error.code`.

For the envelope schema, header reference, verifier code, and error code catalog, refer to [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver).

## Current release limitations

The following limitations apply to webhooks in this release:

* **`account.deleted` is not delivered:** The event type is available for subscription, but Cerby does not currently deliver it and has not defined its payload. To audit account deletions, use the Cerby API or the workspace audit log.
* **Canada region is not supported:** Webhooks are not available for workspaces with data residency in Canada, in the `ca-central-1` region.
* **Ownership transfer does not revoke the previous owner:** An ownership transfer adds the incoming owner without removing the departing one. If your offboarding process depends on the transfer also revoking access, it must reconcile that itself. Refer to [Handle account ownership transfer events](https://help.cerby.com/developer-tools/cerby-webhooks/webhook-events-for-account-ownership-transfer).
* **Secret vault transfers are not delivered:** Vault transfer events cover accounts only, not secrets.

## Related articles

**Setup guides:**

* [Create a webhook](/setup-and-admin/workspace-settings/webhooks/create-a-webhook.md)

**Developer reference:**

* [Implement a webhook receiver](https://help.cerby.com/developer-tools/cerby-webhooks/implement-a-webhook-receiver)
* [Handle breach detection events](https://help.cerby.com/developer-tools/cerby-webhooks/webhook-events-for-credential-breach-detection)
* [Handle account ownership transfer events](https://help.cerby.com/developer-tools/cerby-webhooks/webhook-events-for-account-ownership-transfer)

**Troubleshooting:**

* [Troubleshooting: Webhook deliveries failing](https://help.cerby.com/tips-and-troubleshooting/troubleshooting/webhooks/troubleshooting-webhook-deliveries-failing)


---

# 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.