Skip to main content
A webhook contact is an HTTPS endpoint of yours that receives every breach-monitoring alert as a JSON POST. Add it in the Alerts dialog of the Breach monitoring page (the Webhook tile) — see Alerts & contacts for the dialog itself.

Endpoint requirements

  • HTTPS on a publicly reachable host (no private or link-local addresses, no credentials in the URL, no redirects — a redirect counts as a failure).
  • Answer with any 2xx status within 5 seconds. The response body is ignored; do your processing after replying.
  • Expect the request from a shared, changing source address. We do not publish a fixed IP to allow-list — authenticate deliveries with the signature below.

Request

Payload

string
monitor.new_leaks for a real alert, test for the sample sent by Send test.
string
A UUID unique to this delivery. Use it to ignore a delivery you have already processed.
string
When the alert was sent, ISO 8601.
object
The monitored value and its type: email, username, phone or domain.
array
The breach sources the new records come from. fields lists the kinds of data each source exposes — the names of the columns, never their contents.
string
Where to see the records: the dashboard search.
object
Present for domain monitors (Enterprise) only:
counts.total new records, of which domain belong to the domain’s own e-mail accounts and origin are info-stealer log-ins to the company’s sites; accounts is the number of distinct accounts affected. accounts[] lists the most affected ones (up to 100), each with the kinds it appears in and its record count.
Alerts never contain passwords or any other leaked values — only the sources and the kinds of data. The records themselves are in the dashboard.

Verifying the signature

Every delivery is signed with the contact’s secret — shown once, right after the contact is added. The signature is an HMAC-SHA256 over the timestamp and the raw request body, joined with a dot:
Compute it over the raw body bytes as received (not a re-serialised JSON), compare with a constant-time comparison, and reject deliveries whose timestamp is older than a few minutes to rule out replays.

Delivery rules

  • One request per alert per contact. A connection error or a 5xx answer is retried once, shortly after; any other non-2xx answer is a failure.
  • Monitors are checked once a day and after every import, so a busy monitor can produce several alerts a day; deliveries for different monitors are independent.
  • After 10 consecutive failures the contact is switched off and you are told by e-mail (or Telegram). Fix the endpoint and use Send test: a delivered test switches the contact back on and resets the counter.
  • Deliveries are not queued while a contact is off — alerts from that period are not re-sent. The records themselves are always in the dashboard.

Slack and Discord

Slack and Discord contacts are webhooks too, but their payloads are the services’ own formats (Block Kit and embeds) and they are not signed — the webhook URL itself is the credential. Keep those URLs private; a leaked one can be revoked in Slack or Discord and the contact re-added.