Docs menu

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:

{"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:

HeaderValue
DNSSuper-Signaturet=<unix time>,v1=<hex HMAC-SHA256> (see below)
DNSSuper-Event-Idthe event's id; the same event always carries the same id
DNSSuper-Delivery-Idthis delivery's id; a retry of the same delivery repeats it

A monitor event looks like this:

{
  "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):

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

t=1763208000,v1=a4fbf3198de5e93dc911e36c882de2379c651ccd50886cddcc425d8ae5b2984c

In 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.