# Webhooks

A webhook channel sends each monitor alert, and optionally each finished bulk check, to an HTTPS endpoint you
run, as a signed JSON `POST`. Add one under **Alerts** in your dashboard. Webhook channels come with the Monitor,
Pro and Agency plans; a webhook that only receives bulk completion notices works on any plan once bulk checks are
unlocked.

## Verifying your endpoint

A new webhook channel starts unverified and receives nothing until you verify it. Choose **Verify** and we send
one request:

```json
{"type":"endpoint.verify","challenge":"Vq3...32 characters"}
```

Your endpoint answers with any 2xx status and a body that contains the challenge string. Echoing the request
body back is enough. Once the challenge comes back the channel is active.

## Requests

Every request is a `POST` with `Content-Type: application/json` and these headers:

| Header | Value |
| --- | --- |
| `DNSSuper-Signature` | `t=<unix time>,v1=<hex HMAC-SHA256>` (see below) |
| `DNSSuper-Event-Id` | the event's id; the same event always carries the same id |
| `DNSSuper-Delivery-Id` | this delivery's id; a retry of the same delivery repeats it |

A monitor event looks like this:

```json
{
  "type": "monitor.event",
  "event": {
    "id": 4521,
    "kind": "changed",
    "severity": "warn",
    "title": "The MX records of example.com changed",
    "field": "MX example.com",
    "finding_id": null,
    "before": ["10 mail.example.com."],
    "after": ["10 mx.example.net."],
    "occurred_at": "2026-11-15T12:16:00Z"
  },
  "monitor": {"id": "0190...", "kind": "dns", "target": "example.com", "label": null},
  "links": {"monitor": "https://dnssuper.example/app/monitors/0190..."},
  "delivery_id": "0190...",
  "created_at": "2026-11-15T12:16:02Z"
}
```

A finished bulk check sends `{"type": "job.finished", "data": {...}}` with the job id, tool, status, label,
row counts, credits used and links to the job page and its items. It never contains the domains you checked.

## Checking the signature

The signature is an HMAC-SHA256 of the timestamp, a dot and the raw request body, keyed with the channel's
signing secret (shown once, when you create the channel):

```text
v1 = hex(HMAC_SHA256(secret, "<t>.<raw body>"))
```

Compare it in constant time, and refuse requests whose `t` is more than 5 minutes from your clock. A test
vector: with the secret `whsec_test_secret`, the timestamp `1763208000` and the body
`{"type":"monitor.event"}`, the header is

```text
t=1763208000,v1=a4fbf3198de5e93dc911e36c882de2379c651ccd50886cddcc425d8ae5b2984c
```

In Python:

```python
import hashlib, hmac, time

def verify(secret: bytes, header: str, body: bytes) -> bool:
    parts = dict(p.split("=", 1) for p in header.split(","))
    if abs(time.time() - int(parts["t"])) > 300:
        return False
    expected = hmac.new(secret, parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, parts["v1"])
```

Always check the raw bytes you received, before parsing the JSON.

## Retries

Answer with a 2xx status within 10 seconds. Anything else is retried after about 1 minute, 5 minutes,
30 minutes, 2 hours, 6 hours, 12 hours and 24 hours. After the last attempt fails we pause the channel and
email the account owners; resume it from the dashboard once the endpoint works. A `410 Gone` answer disables
the channel at once. Deliveries are at least once: use `DNSSuper-Delivery-Id` to ignore a repeat.

The delivery log in the dashboard shows each attempt's time and status class (2xx, 4xx, 5xx or timeout), never
the response body.
