> 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/developer-tools/cerby-webhooks/webhook-events-for-credential-breach-detection.md).

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

{% 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 %}

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](/developer-tools/cerby-webhooks/implement-a-webhook-receiver.md).

## 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`                                                                                                                                                       |

{% hint style="danger" %}
**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.
{% endhint %}

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

{% hint style="info" %}
**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.
{% endhint %}

## 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](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook) and [Edit a webhook](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/edit-a-webhook).

## Related articles

**Developer reference:**

* [Implement a webhook receiver](/developer-tools/cerby-webhooks/implement-a-webhook-receiver.md)
* [Handle account ownership transfer events](/developer-tools/cerby-webhooks/webhook-events-for-account-ownership-transfer.md)

**Feature guides:**

* [Explore webhook notifications](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/explore-webhook-notifications)
* [Create a webhook](https://help.cerby.com/setup-and-admin/workspace-settings/webhooks/create-a-webhook)

**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/developer-tools/cerby-webhooks/webhook-events-for-credential-breach-detection.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.