Dark Web Monitoring Webhooks

Monitoring is asynchronous — new breach records are found when new intelligence arrives, not when you ask. Webhooks deliver events to you: PureWL sends an HTTP request to an endpoint you own when an event occurs.

Set up webhooks

Webhooks are configured by PureWL, not through the API:

Send PureWL your webhook URL: the HTTPS endpoint where you want events delivered.
PureWL configures the event subscription on that URL.
PureWL shares the signing secret for that URL. Use it to verify every request.

Each webhook URL has its own signing secret. All event types configured on the same URL, including Dark Web Monitoring and Data Broker Opt-Out events, share that URL’s secret. Store the secret on your server, like your Secret Key, and never expose it in client-side code.

Events

Event	Sent when
`dwm.breach.detected`	One or more of your monitored users’ assets has new breach records since the previous daily check.

dwm.breach.detected

Sent by the daily freshness check (02:00 UTC) when one or more of your monitored users’ assets has new breach records since the previous check. No new breaches means no event that day. The payload’s event field is breach.detected. One delivery covers every affected user; asset values are partially masked.

Payload

string

Event type: breach.detected.

string

When the check ran (ISO 8601, UTC).

number

Page of this delivery, starting at 1.

number

Total pages in this delivery.

number

Number of users with new breach records.

object[]

Users with new breach records.

Show user

string

The user’s uuid, as registered with User Management.

object[]

The user’s assets with new breach records.

Show asset

string

Asset type: email, phone, or domain.

string

The asset, partially masked.

number

Number of new breach records for this asset since the previous check.

Sample payload

dwm.breach.detected

{
  "event": "breach.detected",
  "detectedAt": "2026-10-01T02:00:04.117Z",
  "page": 1,
  "totalPages": 1,
  "totalUsers": 2,
  "users": [
    {
      "uuid": "00000000-0000-0000-0000-000000000001",
      "assets": [
        {
          "type": "email",
          "value": "u************om",
          "newBreaches": 3
        },
        {
          "type": "phone",
          "value": "5*******00",
          "newBreaches": 1
        }
      ]
    },
    {
      "uuid": "00000000-0000-0000-0000-000000000002",
      "assets": [
        {
          "type": "domain",
          "value": "d*******om",
          "newBreaches": 12
        }
      ]
    }
  ]
}

To see the new records themselves, run a Dark Web Scan for the asset.

Verify webhook signatures

Every webhook request is signed, so your endpoint can confirm it came from PureWL and was not altered. Accept a request only when its signature is valid. Reject any request with a missing or invalid signature.


Signature header	`x-outpost-signature`, in the format `v0=<hex-digest>`
Algorithm	HMAC-SHA256
Signed content	The raw request body: the exact bytes received, before any parsing or re-serializing
Key	The signing secret PureWL shared for this webhook URL

To verify a request:

Compute the HMAC-SHA256 digest of the raw request body, using the signing secret as the key.
Hex-encode the digest.
Compare it with the value after v0= in the x-outpost-signature header.
Use a constant-time comparison, to prevent timing attacks.
Accept the request only if the two values match.

Compute the signature over the body exactly as received. If your framework parses the JSON first and you re-serialize it, the bytes can change and valid requests will fail verification.

import crypto from "node:crypto";
import express from "express";

const app = express();
const SIGNING_SECRET = process.env.WEBHOOK_SIGNING_SECRET;

// express.raw() keeps the body as the exact bytes received.
app.post("/webhooks/purewl", express.raw({ type: "*/*" }), (req, res) => {
  const header = req.get("x-outpost-signature") || "";
  if (!header.startsWith("v0=")) return res.sendStatus(401);

  const expected = Buffer.from(
    crypto.createHmac("sha256", SIGNING_SECRET).update(req.body).digest("hex")
  );
  const received = Buffer.from(header.slice(3));
  if (expected.length !== received.length || !crypto.timingSafeEqual(expected, received)) {
    return res.sendStatus(401);
  }

  res.sendStatus(200); // respond first, then process
  const event = JSON.parse(req.body.toString("utf8"));
  // queue `event` for processing
});

import hashlib
import hmac
import os

from flask import Flask, abort, request

app = Flask(__name__)
SIGNING_SECRET = os.environ["WEBHOOK_SIGNING_SECRET"].encode()


@app.post("/webhooks/purewl")
def purewl_webhook():
    raw = request.get_data()  # the exact bytes received
    header = request.headers.get("x-outpost-signature", "")
    if not header.startswith("v0="):
        abort(401)

    expected = hmac.new(SIGNING_SECRET, raw, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, header[3:]):
        abort(401)

    event = request.get_json()
    # queue `event` for processing
    return "", 200

Handling events

Accept HTTPS only, use an unguessable endpoint path, and verify the signature of every request.
Respond immediately, then process asynchronously, so slow handling is not mistaken for a failed delivery.
Expect duplicates and out-of-order delivery, and skip event types you do not recognize rather than erroring.
Read every page — when totalPages is greater than 1, the event arrives in several deliveries.

Overview

User Management