Deliver matches by email and webhook

Delivery settings decide where a monitor sends a new match: email, a webhook, or both. You create them once for your organization and attach them to monitors by ID. In the dashboard they are under Monitoring → Delivery settings. Email uses up to three pieces. Recipients are the addresses it goes to. A template sets the subject and body. A sender is your own mail server, and it is optional: without one, email goes out through the platform’s mail server. A webhook is one signed HTTP POST per match. Delivery is a notification, not the record. Every match is stored and readable through the match endpoints whether delivery succeeds or not. Neither email nor webhooks are retried.

Availability and cost

Availability: recipients, the system Default Template and the platform’s mail server are on every plan with a license in force. Your own templates and senders need the Custom Email Server plan feature. Webhooks need the Webhooks plan feature. Cost: no metered allowance and no capacity slots. Each organization can hold up to 200 recipients, 200 senders and 10 webhooks. Templates have no cap. Without the plan feature, these calls return 403:

{
  "detail": "This feature is not included in your plan."
}

Every webhook call (list, create, read, update and delete) needs Webhooks.
Creating, updating and deleting senders and templates needs Custom Email Server. Listing and reading them is open on every plan.

These calls return the same body when your license is not in force. Every other delivery call returns 403 with {"detail": "Your license is not active."} instead. A 429 here is the rate limit or the API Calls allowance described in Rate limits.

How defaults work

Recipients, senders, templates and webhooks each carry an is_default flag. Once your organization has at least one item of a type, exactly one of them is the default:

The first item you create becomes the default. For templates, the system Default Template starts as the default, so a template you create becomes the default only when you send is_default: true.
Setting is_default: true on another item moves the flag to it.
You cannot clear the flag on the default directly. Set another item as default instead. Sending is_default: false for the current default returns 400.
When you delete the default, the most recently created remaining item becomes the default.

The API never attaches a default to a monitor for you. A monitor uses exactly the IDs you send.

Recipients

A recipient is an email address. Create one with alert_system_setting_create_recipient. Both fields are required.

curl https://client-api.leak.center/api/service/alert_system_setting_create_recipient/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"email": "soc@acme.com", "is_default": false}'

{
  "id": 12,
  "email": "soc@acme.com",
  "is_default": true
}

This was the organization’s first recipient, so it became the default. Pass its id in a monitor’s recipients.

Up to 200 recipients per organization. The 201st returns 400 with You can only have 200 recipient emails.
alert_system_setting_update_recipient is a PUT that takes the same two fields.
The API does not check for duplicates: an address that already exists is added again as a new recipient. List recipients first and reuse the existing id.
A recipient that a monitor uses cannot be deleted. The call returns 400 with Cannot delete recipient email. It is currently used by the following alert rules: and the monitor names. Remove it from those monitors, or delete them, first.

Email templates

A template is the subject and HTML body of the email. The platform sends body exactly as it is stored, with the placeholders filled in. It adds no layout, logo or button of its own. The designed layout in the dashboard’s template editor is HTML that the dashboard writes into body when you save a template there, so a template saved in the dashboard returns that full HTML, and a template you create through the API sends only the HTML you write. Every organization has a system-created Default Template with is_system_created: true. It works on every plan, and it cannot be deleted. Find its id with alert_system_setting_get_template_list:

curl https://client-api.leak.center/api/service/alert_system_setting_get_template_list/ \
  -H "X-API-Key: YOUR_API_KEY"

[
  {
    "id": 5,
    "name": "Default Template",
    "subject": "Alert Notification: New Matches Found for Your Alert Rule \"{alert_rule_name}\"",
    "body": "<p>Hello,</p>...",
    "is_system_created": true,
    "is_default": true
  }
]

With Custom Email Server you can write your own. alert_system_setting_create_template and alert_system_setting_update_template take name, subject, body and is_default, all required.

curl https://client-api.leak.center/api/service/alert_system_setting_create_template/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme SOC",
        "subject": "[DarknetSearch] {number_of_hits} new results for {alert_rule_name}",
        "body": "<p>{current_date}: {number_of_hits} new results on {service} for {alert_rule_name}.</p><p><a href=\"{match_detail_link}\">Review the results</a></p>",
        "is_default": false
      }'

The body must contain five placeholders, or the call returns 400 naming the missing ones. The platform fills them in the subject and the body when it sends:

Placeholder	Becomes
`{current_date}`	The send time in UTC, as `2026-10-08 09:30:12`.
`{alert_rule_name}`	The monitor’s `name`.
`{number_of_hits}`	The match’s results that are not excluded.
`{service}`	The source’s catalog `name`, for example `phishing`.
`{match_detail_link}`	The URL that opens the match in the dashboard, in your organization. It is a bare URL, so put it in an `<a href>` to make a button or link.

Two more placeholders are optional: {total_results} (every result, excluded ones included) and {excluded_count}. Send body on one line. If it contains any newline, the platform wraps each block separated by a blank line in <p>, turns every other newline into <br> and removes the newlines. It does this to HTML too, so a multi-line HTML body gains stray line breaks. A template that a monitor uses cannot be deleted. The call returns 400 with Cannot delete email template. It is currently used by the following alert rules: and the monitor names.

Senders

A sender is your own SMTP server. Without one, a monitor’s sender stays null and email goes out through the platform’s mail server. Your own sender needs Custom Email Server. alert_system_setting_create_sender requires every field, including username and password when authentication_required is false:

curl https://client-api.leak.center/api/service/alert_system_setting_create_sender/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "email": "alerts@acme.com",
        "server_host": "smtp.acme.com",
        "port": 587,
        "encryption_method": "TLS",
        "authentication_required": true,
        "username": "alerts@acme.com",
        "password": "YOUR_SMTP_PASSWORD",
        "is_default": true
      }'

Field	Notes
`email`	The From address.
`server_host`	The SMTP host.
`port`	The SMTP port. Write-only.
`encryption_method`	`SSL` or `TLS`. See below.
`authentication_required`	`true` logs in with `username` and `password` before sending.
`username`, `password`	Write-only. The password is stored encrypted.
`is_default`	See How defaults work.
`is_system_created`	Read-only. Always `false` on senders you create.

encryption_method picks how the connection is secured:

SSL opens an encrypted connection from the first byte (implicit TLS). Mail servers usually offer it on port 465.
TLS connects in plain text, then upgrades with STARTTLS before logging in. Mail servers usually offer it on port 587.

alert_system_setting_update_sender is a PUT that requires every field again, password included. Up to 200 senders per organization: the 201st returns 400 with You can only have 200 sender emails. A sender that a monitor uses cannot be deleted. The call returns 400 with Cannot delete sender email. It is currently used by the following alert rules: and the monitor names. Test a sender before a monitor depends on it. alert_system_setting_test_email sends a short plain-text message through the sender:

curl https://client-api.leak.center/api/service/alert_system_setting_test_email/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"sender_id": 8, "recipient": "soc@acme.com"}'

The call returns 202 with {"status": "success"} once the message is queued. It does not report whether the message arrived, so check the inbox. A sender_id that is not yours returns 400.

Webhooks

A webhook receives each delivered match as one HTTP POST. Webhooks need the Webhooks plan feature. Create one with alert_system_setting_create_webhook. All four fields are required.

curl https://client-api.leak.center/api/service/alert_system_setting_create_webhook/ \
  -X POST \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "name": "Acme SIEM",
        "url": "https://hooks.acme.com/darknetsearch",
        "headers": {"X-Acme-Source": "darknetsearch"},
        "is_default": false
      }'

{
  "id": 3,
  "name": "Acme SIEM",
  "url": "https://hooks.acme.com/darknetsearch",
  "headers": {"X-Acme-Source": "darknetsearch"},
  "secret": "9f2c4e7a1b3d5f60718293a4b5c6d7e8f9a0b1c2d3e4f5061728394a5b6c7d8e",
  "is_default": true
}

url — a valid URL of up to 2,048 characters.
headers — a JSON object sent with every delivery. Send {} for none. The platform always sets Content-Type, User-Agent and X-AlertSystem-Signature itself, and those win over a custom header with the same name.
secret — 64 hexadecimal characters, generated by the platform and read-only. A value you send is ignored, and an update never changes it. For a new secret, create a new webhook, point your monitors at it, then delete the old one.

Up to 10 webhooks per organization. A webhook that a monitor uses cannot be deleted: the call returns 400 and names the monitors. Point them at another webhook, or delete them, first.

The payload

Every URL that is not Slack, Discord or Microsoft Teams receives this JSON:

{
  "match_detail_id": 4821,
  "alert_rule_id": 731,
  "alert_rule_name": "Acme phishing references",
  "service": "Phishing",
  "total_matches": 15,
  "excluded_matches": 2,
  "results_url": "https://dashboard.darknetsearch.com/alerts/incidents/4821/results?org_id=310",
  "timestamp": "2026-10-08T09:30:12.481203+00:00"
}

Field	Meaning
`match_detail_id`	The match ID. Read its results with `alert_system_alert_get_alert_match_detail_results`.
`alert_rule_id`	The monitor ID.
`alert_rule_name`	The monitor’s `name`.
`service`	The source’s name label, as in the Source column of the data source table, for example `Phishing` or `Data Brokers`. It is not the catalog `alias`.
`total_matches`	Every result in the match, excluded ones included.
`excluded_matches`	Results that hit the monitor’s exclusion list. `total_matches` minus `excluded_matches` is what is new to you.
`results_url`	A dashboard link to the match. The platform adds your organization to the link. It is not an API parameter.
`timestamp`	When the payload was built, in ISO 8601 UTC.

The payload tells you that a match exists. It does not carry the results. Fetch them by match_detail_id, as described in Read and triage matches.

Chat platforms

The platform picks a message format from the webhook URL:

URL contains	Format
`hooks.slack.com`	A Slack message with the source, the counts and a View Results link.
`discord.com/api/webhooks`	A Discord embed with the same content.
`powerplatform.com`, `webhook.office.com` or `outlook.office.com`	A Microsoft Teams message carrying an Adaptive Card 1.4 with Service, Total Matches, Excluded Matches, Time and a View Results link.

For Microsoft Teams, use the channel workflow Send webhook alerts to a channel and paste the URL it generates. The chat formats carry no match_detail_id or alert_rule_id. To process matches in code, use a generic URL.

Verify the signature

Every request carries X-AlertSystem-Signature: sha256= followed by a hex HMAC-SHA256 of the raw request body, keyed with the webhook’s secret. Check it before you trust the payload:

Read the raw body bytes exactly as received, before any JSON parsing.
Compute the HMAC-SHA256 of those bytes with your secret.
Compare it, in constant time, with the header value after the sha256= prefix.
Reject a mismatch. Return any 2xx to accept the delivery.

import hashlib
import hmac

def is_valid(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    received = signature_header.removeprefix("sha256=")
    return hmac.compare_digest(expected, received)

Requests also carry Content-Type: application/json and User-Agent: AlertSystem/1.0.

Delivery behavior

One POST per match, sent right after the run that recorded it.
Only matches with at least one result that is not excluded are sent.
The platform waits 30 seconds for an answer. Any 2xx counts as delivered.
A failed or slow delivery is not retried, and the API keeps no record of it. Read missed matches from the match list.

Bounced emails

The platform sends one message per recipient. When the mail server refuses the message for a recipient, the platform records a bounced email with the server’s reason. When it cannot connect to or log in to the sender, nothing is sent and nothing is recorded, so use the test message to check a sender. alert_system_setting_get_bounced_email_list returns bounces newest first, in pages:

curl -G https://client-api.leak.center/api/service/alert_system_setting_get_bounced_email_list/ \
  -H "X-API-Key: YOUR_API_KEY" \
  --data-urlencode "alert_rule_ids=731" \
  --data-urlencode "from_date=2026-10-01"

Parameter	What it does
`page`, `page_size`	1-based page. `page_size` defaults to `10`, max `100`. Raise `page` until `next` is `null`, and don’t call the `next` URL itself.
`alert_rule_ids`	Comma-separated monitor IDs.
`recipient_email`, `sender_email`	An exact address.
`from_date`, `to_date`	`YYYY-MM-DD`, inclusive, on the day the bounce was recorded.

Each bounce has id, alert_rule (the monitor ID), match_detail (the match ID), recipient_email, sender_email, reason and creation_date. Read one with alert_system_setting_get_bounced_email_detail and remove one with alert_system_setting_delete_bounced_email.

Endpoints

Action	Endpoint
List recipients	`GET /api/service/alert_system_setting_get_recipient_list/`
Create a recipient	`POST /api/service/alert_system_setting_create_recipient/`
Get a recipient	`GET /api/service/alert_system_setting_get_recipient_detail/{id}/`
Update a recipient	`PUT /api/service/alert_system_setting_update_recipient/{id}/`
Delete a recipient	`DELETE /api/service/alert_system_setting_delete_recipient/{id}/`
List templates	`GET /api/service/alert_system_setting_get_template_list/`
Create a template	`POST /api/service/alert_system_setting_create_template/`
Get a template	`GET /api/service/alert_system_setting_get_template_detail/{id}/`
Update a template	`PUT /api/service/alert_system_setting_update_template/{id}/`
Delete a template	`DELETE /api/service/alert_system_setting_delete_template/{id}/`
List senders	`GET /api/service/alert_system_setting_get_sender_list/`
Create a sender	`POST /api/service/alert_system_setting_create_sender/`
Get a sender	`GET /api/service/alert_system_setting_get_sender_detail/{id}/`
Update a sender	`PUT /api/service/alert_system_setting_update_sender/{id}/`
Delete a sender	`DELETE /api/service/alert_system_setting_delete_sender/{id}/`
Send a test message	`POST /api/service/alert_system_setting_test_email/`
List webhooks	`GET /api/service/alert_system_setting_get_webhook_list/`
Create a webhook	`POST /api/service/alert_system_setting_create_webhook/`
Get a webhook	`GET /api/service/alert_system_setting_get_webhook_detail/{id}/`
Update a webhook	`PUT /api/service/alert_system_setting_update_webhook/{id}/`
Delete a webhook	`DELETE /api/service/alert_system_setting_delete_webhook/{id}/`
List bounced emails	`GET /api/service/alert_system_setting_get_bounced_email_list/`
Get a bounced email	`GET /api/service/alert_system_setting_get_bounced_email_detail/{id}/`
Delete a bounced email	`DELETE /api/service/alert_system_setting_delete_bounced_email/{id}/`

Get started

Search

Leaked credentials

Assess & report

Monitors

Domain monitoring

Downloads & exports

Changelog

Deliver matches by email and webhook

Availability and cost

How defaults work

Recipients

Email templates

Senders

Webhooks

The payload

Chat platforms

Verify the signature

Delivery behavior

Bounced emails

Endpoints

​Availability and cost

​How defaults work

​Recipients

​Email templates

​Senders

​Webhooks

​The payload

​Chat platforms

​Verify the signature

​Delivery behavior

​Bounced emails

​Endpoints

Availability and cost

How defaults work

Recipients

Email templates

Senders

Webhooks

The payload

Chat platforms

Verify the signature

Delivery behavior

Bounced emails

Endpoints