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 — 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.

Who can use this feature?

Workspace Owners, Super Admins, and Admins
Supported using the Cerby web app and the Cerby API

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.

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.

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:

Create a webhook endpoint in your workspace settings. Specify the HTTPS URL, select the event types to subscribe to, and choose a signing algorithm.
Copy the signing key material when it is displayed. Cerby shows it only once.
Share the signing key and the endpoint URL with the developer who will implement the receiver.

For detailed steps, refer to Create a webhook.

For developers

To implement a webhook receiver, complete the following steps:

Set up an HTTPS endpoint that can accept POST requests from Cerby.
Implement signature verification using the reference verifier for your language.
Deduplicate incoming requests using the X-Cerby-Delivery header.
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.

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.

Setup guides:

Create a webhook

Developer reference:

Implement a webhook receiver

Troubleshooting:

Troubleshooting: Webhook deliveries failing

Last updated 16 days ago

Was this helpful?