Webhook events
A webhook delivers each event you subscribe to as an HTTP POST to your endpoint. This page is the reference for what is sent: the headers,
how to verify the signature, the retry policy, the envelope, and the data of every event. To set up endpoints and alert rules in the panel, see the
Webhooks & Alerts guide. The endpoints themselves are in the API reference
(POST /v1/webhooks).
Delivery
Each delivery is POST <webhook url> with Content-Type: application/json and these headers:
| Header | Meaning |
|---|---|
X-Webhook-Event | Event name, the same as event in the body. |
X-Webhook-Event-Id | Id of the event, the same as id in the body. Identical for every webhook that receives the event and for every retry: deduplicate on it. |
X-Webhook-Delivery | Id of this delivery attempt (see GET /v1/webhooks/{id}/deliveries). |
X-Webhook-Timestamp | Unix time of the attempt. It is part of the signed string. |
X-Webhook-Signature | sha256=<hex>, an HMAC-SHA256 of "<timestamp>.<raw body>" with your webhook secret. |
Verify the signature
Compute the HMAC over the timestamp, a dot, and the raw request body (before any JSON parsing), compare it in constant time, and reject deliveries whose timestamp is more than a few minutes old.
# Python
import hmac, hashlib
def verify(secret: str, timestamp: str, body: bytes, signature: str) -> bool:
expected = "sha256=" + hmac.new(secret.encode(), f"{timestamp}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature)
// Node.js
const crypto = require('crypto');
function verify(secret, timestamp, rawBody, signature) {
const expected = 'sha256=' + crypto.createHmac('sha256', secret)
.update(timestamp + '.').update(rawBody).digest('hex');
return signature.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected));
}
Retries
Any HTTP 2xx answer counts as delivered. A different status or no answer within 10 seconds is a failure and the delivery is retried after
1, 5, 30 and 120 minutes; after the fifth attempt it is abandoned. Deliveries for an account in
Restricted Mode wait until the balance is settled and are then sent.
Because of retries, an endpoint can receive the same event more than once: deduplicate on X-Webhook-Event-Id.
Envelope
Every event has the same envelope (version 1):
{
"id": "3f6c1e0a-7d8b-4b7e-9c1a-2f3e4d5c6b7a",
"version": 1,
"event": "record.updated",
"account_id": 139111,
"timestamp": "2026-10-22T10:15:30Z",
"data": { "...": "event-specific, see the table below" }
}
version changes only when an existing field of the envelope or of data changes meaning or type. New events and new keys in
data are additions and do not change it, so ignore keys you do not know.
Events
| Event | When | data |
|---|---|---|
record.created | A record was added (API, bulk, template apply, view sync). Not sent for the records of a zone batch or an RRset PUT (see zone.batch_applied, rrset.updated). | record: the record as returned by the API (id, domain_id, domain_name, name, type, content, ttl, prio, dynamic, change_date, soa_serial) |
record.updated | A record was changed. | record: the record after the change (same shape); old: the previous name, type, content, ttl, prio (absent keys when unknown) |
record.deleted | A record was removed (API, bulk, template apply). | record_id, soa_serial; record: what was removed (name, type, content, ttl, prio, zone; absent when unknown) |
ddns.updated | A DynDNS client changed the address of a dynamic record (only real changes, not heartbeats). | hostname, old_ip, new_ip, record |
zone.created | A zone was added (POST /v1/domains/external, domain registration). | zone, domain_id |
zone.deleted | A zone was removed (DELETE /v1/domains/{domain}). | zone |
zone.batch_applied | A zone batch was applied (POST /v1/zones/{zone}/batch, not a dry run). One event per batch: a batch sends no record.* events (the audit log has every record). | zone, batch_id, applied (operations per list), records (created, updated, deleted), soa_serial, comment (or null), changes (at most 100 of action, name, type, before, after), changes_truncated |
rrset.updated | An RRset was set or deleted (PUT or DELETE /v1/zones/{zone}/rrsets/{name}/{type}, not a dry run, and only when something changed). One event for the RRset, not one per value: no record.* events. | zone, name, type, action (create, update, delete), before and after (ttl, records with content, prio; null when absent), changes (added, removed, updated, ttl_changed), soa_serial |
zone.imported | A zone file was imported (POST /v1/zones/{zone}/import, not a dry run). One event per import, not one per record. | zone, created, skipped, errors |
dnssec.enabled | DNSSEC was enabled on a zone. | zone, algorithm |
dnssec.disabled | DNSSEC was disabled on a zone. | zone |
apikey.created | An API key was created. | key_id, name, key_prefix, scopes (never the key itself) |
apikey.revoked | An API key was revoked. | key_id, name, key_prefix |
apikey.rotated | An API key was rotated: the secret was replaced. | key_id, name, key_prefix, previous_prefix, grace_period_hours (never a secret) |
team.member_added | An invitation was accepted. | member_id, member_username, role |
team.member_removed | A member was removed from the team. | member_id, member_username, role |
alert.fired | An alert rule triggered an incident. | rule_type, zone, value, threshold, extra keys per rule type: recent_qps, prev_qps (spike_event); targets (dangling_cname: zone, record, target); changes (record_changed: zone, name, type, action, old, new, old_ttl, new_ttl, by, source, at); zones (delegation_changed: zone, previous, current, points_to_us). For these three value is the number of findings and lists are capped at 50. test: true is present only on a test sent with POST /v1/alert-rules/{id}/test (made-up findings, no incident) |
ssl.expiring | A monitored certificate is expiring or expired. | domain, port, status, expires_at, days_left, issuer |
team.invited | A team invitation was sent. | email, role, actor |
team.role_changed | A team member's role was changed. | member_id, member_username, new_role, actor |
apikey.updated | An API key's name or restrictions were changed. | key_id, name, key_prefix, widened (restrictions loosened), actor |
domain.registered | A domain was registered. | domain, period, actor |
domain.renewed | A domain was renewed. | domain, period, actor |
domain.transfer_requested | A domain transfer was ordered. | domain, actor |
template.applied | A template was applied to a zone (the record changes also arrive as record.*). | zone, template_id, created, updated, deleted, errors, actor |
view.changed | A split-horizon view or its networks or zone attachment changed. | action (create, delete, attach, detach, move, network_add, network_remove, sync_apply), view_id (old_view_id, new_view_id for move), network, zone, actor |
ssl.requested | A certificate was ordered. | domain, certificate_id, actor |
ssl.renewed | A certificate renewal was started by a person. | domain, certificate_id, actor |
ssl.deleted | A certificate was deleted. | domain, certificate_id, actor |
account.password_changed | The account password was changed or reset. | via, actor |
account.totp_enabled | Two-factor (TOTP) was switched on. | actor |
account.totp_disabled | Two-factor (TOTP) was switched off. | actor |
account.totp_recovery_regenerated | New TOTP recovery codes were generated. | actor |
account.passkey_added | A passkey was registered. | device_name, actor |
account.passkey_removed | A passkey was removed. | actor |
account.profile_updated | Profile data was changed. | fields: names of the changed fields (never the values), actor |
webhook.created | A webhook endpoint was added (the URL is not included). | id, name, events, actor |
webhook.deleted | A webhook endpoint was removed. | id, actor |
webhook.test (sent by POST /v1/webhooks/{id}/test) uses the same envelope with data.message. It cannot be subscribed to.
Who did it: actor
The events from team.invited to webhook.deleted also appear in the Audit Log and carry
data.actor with id, username and source (web, api or dyndns).
Only the keys listed in the table are sent. Logins, payments and secrets are never included.
Slack, Discord, Microsoft Teams and Telegram
A webhook has a format (default generic). With generic you receive the signed JSON described above. With
slack, discord, teams or telegram the same event is sent as a ready-made chat message, so the URL can be the incoming-webhook
URL of that service. The signature headers are sent in every format, and chat services ignore them. A chat delivery counts as successful on any
2xx answer, like a generic one, and a wrong URL shows up as failed deliveries. Step-by-step setup is in the
Webhooks & Alerts guide.
| Format | Body sent | URL |
|---|---|---|
slack | {"text": "..."} with a bold title and one bullet per detail | Slack incoming webhook |
discord | {"content": "..."}, at most 2000 characters; mentions never notify anybody | Discord webhook URL |
teams | An Adaptive Card message | Microsoft Teams Workflows webhook |
telegram | Plain text, at most 4096 characters | Created with bot_token and chat_id instead of url; the token is never shown again |
Next steps
- Create endpoints and alert rules, and test the chain: Webhooks & Alerts.
- Account states that pause deliveries: Restricted Mode.
- What changed in the API and when: API changelog.