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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.whiteintel.io/whiteintel-api-doc/webhooks/whiteintel-webhook-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.