> For the complete documentation index, see [llms.txt](https://docs.whiteintel.io/whiteintel-api-doc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.whiteintel.io/whiteintel-api-doc/webhooks/whiteintel-webhook-api.md).

# WhiteIntel Webhook API

WhiteIntel webhooks allow your organization to receive **real-time alerts** when your **watchlist items** (such as domains, IPs, hostames, or emails) are detected in leaked stealer logs.

***

### 🔧 Setup

To configure a webhook:

1. Go to your **WhiteIntel dashboard**
2. Set your receiving **HTTPS endpoint**
3. A secure **HMAC secret** will be auto-generated

> ⚠️ Configuring a webhook will override any existing configuration.

#### Endpoint Requirements

* Must use `https://` (or `http://` in dev/test)
* Must not point to internal/private addresses (e.g. `localhost`, `.local`, `127.0.0.1`)
* Must not target WhiteIntel-owned domains

***

### 🔐 Security & Signature

Every webhook POST is signed with an **HMAC SHA256** signature.

{% hint style="danger" %}
NEVER PROCESS THE REQUEST BEFORE VERIFYING THE SIGNATURE.
{% endhint %}

#### Headers

| Header                | Description                   |
| --------------------- | ----------------------------- |
| `X-Signature`         | Base64-encoded HMAC signature |
| `X-Signature-Version` | Currently always `"v1"`       |
| `X-Timestamp`         | ISO 8601 UTC timestamp        |
| `User-Agent`          | `WhiteIntel-Webhook`          |

#### Signature Generation (example)

```js
// Pseudo-code for generating the HMAC signature
signature = base64(HMAC_SHA256(timestamp, secret_key))
```

### 📬 Events & Payload Structure

Webhook notifications are triggered for the following types based on your watchlist:

* `consumer`
* `corporate`
* `email`
* `ip`
* `hostname`

#### Sample Payload: `consumer`

```json
{
  "type": "consumer",
  "value": "example.com",
  "description":"As part of WhiteIntel's dark web surveillance, the specified consumer accounts have been found exposed in stolen credentials.",
  "count": 8,
  "usernames": [
    ["user2@gmail.com", 5],
    ["user1@gmail.com", 3]
  ],
  "event_date": "2025-04-10 12:00:00",
  "source": "watchlist_monitor"
}


```

#### Sample Payload: `corporate` 

```json
{
  "type": "corporate",
  "value": "internal.corp.com",
  "description":"As part of WhiteIntel's dark web surveillance, the specified corporate accounts have been found exposed in stolen credentials.",
  "count": 5,
  "usernames": [
    ["ceo@corp.com", 2],
    ["it@corp.com", 1]
  ],
  "event_date": "2025-04-10 12:00:00",
  "source": "watchlist_monitor"
}
```

#### Sample Payload: `email` 

```json
{
  "type": "email",
  "value": "staff@example.com",
  "description": "As part of WhiteIntel's dark web surveillance, the specified email address has been found exposed in stolen credentials.",
  "count": 2,
  "usernames": [
    ["staff@example.com", 2]
  ],
  "event_date": "2025-04-10 06:00:00",
  "source": "watchlist_monitor"
}
```

#### Sample Payload: `ip` 

```json
{
  "type": "ip",
  "value": "192.0.2.1",
  "description": "As part of WhiteIntel's dark web monitoring, the following IP addresses have been identified as compromised by stealer malware.",
  "count": 1,
  "event_date": "2025-04-10 08:00:00",
  "source": "watchlist_monitor"
}
```

#### Sample Payload: `computername`

```json
{
  "type": "hostname",
  "value": "DESKTOP-HACKED01",
  "description": "As part of WhiteIntel's dark web monitoring, the specified Computer name have been identified as compromised by stealer malware.",
  "count": 1,
  "event_date": "2025-04-10 07:00:00",
  "source": "watchlist_monitor"
}
```

### Webhook Simulation

In order to simulate webhook calls before deploying to production, visit your Webhook page on WhiteIntel platform.

<figure><img src="/files/ca4M9L2gsMBIVLVXemwO" alt=""><figcaption></figcaption></figure>