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