Ctrlk
CerbyDeveloper PortalSupportWeMakeCerby
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Handle breach detection events

This article describes how to handle the credential breach detection webhook event, including the fields it carries and why it reports an error without being a failure.

Cerby sends the account.credentials.breach_detected webhook event when the password stored on a Cerby-managed account is found in a known breach corpus. It helps you route credential exposures into your own security tooling by delivering the affected account and the exposure count as soon as Cerby records the detection.

Who can use this feature?

  • Workspace Owners, Super Admins, and Admins

  • Supported using the Cerby web app and the Cerby API

This event is one of the event types you can subscribe to when you create a webhook. For the envelope structure, signature verification, and delivery guarantees that apply to every Cerby event, refer to Implement a webhook receiver.

Key benefits

The following are the main benefits of subscribing to credential breach detection events:

  • Immediate exposure signal: Receive the affected account as soon as Cerby records a detection, rather than discovering the exposure during a periodic audit.

  • Machine-readable severity: Each event carries the number of times the password appears in the breach corpus, so your integration can prioritize rotation without a human reading the alert.

  • No secret material on the wire: The event identifies the account and the exposure, and never carries the password or a hash of it.

Event payload

The following table describes the data fields this event carries:

Field
Type
Description

account_id

string

The Cerby-managed account whose stored password was found in the breach corpus, as 32-character undashed hexadecimal.

breached_credential_id

string

The identifier of the breach record Cerby created for this detection, as 32-character undashed hexadecimal.

breach_count

integer

How many times the password appears in the known breach corpus.

detected_at

string (RFC 3339)

When Cerby recorded the detection, always in UTC with an explicit +00:00 offset.

This event also carries an error object, even though it is not a failure. The following table describes its values:

Field
Value

code

Always CredentialBreached

message

A human-readable sentence that restates breach_count, for example "The password stored on this account has appeared 42 times in the known breach corpus and should be rotated."

user_action

Always review_credentials

IMPORTANT: The error object is what marks this event as actionable, but this event is not a failure. If your integration treats the presence of error as evidence that an operation failed, it will mislabel breach alerts. If it infers the presence of error from a .failed event name, it will drop them. Test for the error key instead.

Delivery behavior

The following behaviors determine when you receive this event and what you can infer from it:

  • One detection per account and password: Cerby emits this event once for a given account and stored password. A repeat report and a rising exposure count are deliberately silent. A second detection for the same account therefore means the password was rotated and the new password was then found in the corpus.

  • Detection timing varies: The user's own device reports the detection on either of two routes, immediately when someone reveals the credential in Cerby, or during a periodic background scan. On the scan route, delivery latency follows the scan cycle, which reschedules each account roughly 24 hours out. A credential that is neither revealed nor scanned produces nothing.

  • The count measures corpus occurrences, not separate incidents: breach_count is how many times the password appears in the corpus, not the number of distinct data breaches it was found in.

  • The detection is client-asserted: The user's device computes the match and reports it. Cerby records what the device reports.

  • No secret material is included: The password and its full hash never leave the user's device. Cerby receives only a five-character prefix of the hash, which is what it uses to look up candidate matches, and the device performs the match itself. No password material exists on the envelope to include.

  • There is no resolution event: Nothing reports that a flagged credential was remediated. A password change emits its own account.credentials.updated or account.credentials.rotated event, but neither carries breached_credential_id, so neither can be tied back to a particular detection. Reconcile against the Cerby API instead.

NOTE: The one-detection-per-password bound applies to detections, not to HTTP deliveries. The at-least-once delivery guarantee still applies, so deduplicate on event_id or X-Cerby-Delivery rather than treating every request as a new detection.

Subscribing to this event

You can subscribe to this event individually when you create or edit a webhook, or include it by selecting the Failures-only or Everything preset. The Failures-only preset includes it because it asks you to act, even though its name does not end in failed.

For the steps to subscribe, refer to Create a webhook and Edit a webhook.

Related articles

Developer reference:

Feature guides:

Troubleshooting:

Last updated

Was this helpful?