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:

HeaderMeaning
X-Webhook-EventEvent name, the same as event in the body.
X-Webhook-Event-IdId 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-DeliveryId of this delivery attempt (see GET /v1/webhooks/{id}/deliveries).
X-Webhook-TimestampUnix time of the attempt. It is part of the signed string.
X-Webhook-Signaturesha256=<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

EventWhendata
record.createdA 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.updatedA record was changed.record: the record after the change (same shape); old: the previous name, type, content, ttl, prio (absent keys when unknown)
record.deletedA 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.updatedA DynDNS client changed the address of a dynamic record (only real changes, not heartbeats).hostname, old_ip, new_ip, record
zone.createdA zone was added (POST /v1/domains/external, domain registration).zone, domain_id
zone.deletedA zone was removed (DELETE /v1/domains/{domain}).zone
zone.batch_appliedA 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.updatedAn 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.importedA 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.enabledDNSSEC was enabled on a zone.zone, algorithm
dnssec.disabledDNSSEC was disabled on a zone.zone
apikey.createdAn API key was created.key_id, name, key_prefix, scopes (never the key itself)
apikey.revokedAn API key was revoked.key_id, name, key_prefix
apikey.rotatedAn API key was rotated: the secret was replaced.key_id, name, key_prefix, previous_prefix, grace_period_hours (never a secret)
team.member_addedAn invitation was accepted.member_id, member_username, role
team.member_removedA member was removed from the team.member_id, member_username, role
alert.firedAn 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.expiringA monitored certificate is expiring or expired.domain, port, status, expires_at, days_left, issuer
team.invitedA team invitation was sent.email, role, actor
team.role_changedA team member's role was changed.member_id, member_username, new_role, actor
apikey.updatedAn API key's name or restrictions were changed.key_id, name, key_prefix, widened (restrictions loosened), actor
domain.registeredA domain was registered.domain, period, actor
domain.renewedA domain was renewed.domain, period, actor
domain.transfer_requestedA domain transfer was ordered.domain, actor
template.appliedA template was applied to a zone (the record changes also arrive as record.*).zone, template_id, created, updated, deleted, errors, actor
view.changedA 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.requestedA certificate was ordered.domain, certificate_id, actor
ssl.renewedA certificate renewal was started by a person.domain, certificate_id, actor
ssl.deletedA certificate was deleted.domain, certificate_id, actor
account.password_changedThe account password was changed or reset.via, actor
account.totp_enabledTwo-factor (TOTP) was switched on.actor
account.totp_disabledTwo-factor (TOTP) was switched off.actor
account.totp_recovery_regeneratedNew TOTP recovery codes were generated.actor
account.passkey_addedA passkey was registered.device_name, actor
account.passkey_removedA passkey was removed.actor
account.profile_updatedProfile data was changed.fields: names of the changed fields (never the values), actor
webhook.createdA webhook endpoint was added (the URL is not included).id, name, events, actor
webhook.deletedA 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.

FormatBody sentURL
slack{"text": "..."} with a bold title and one bullet per detailSlack incoming webhook
discord{"content": "..."}, at most 2000 characters; mentions never notify anybodyDiscord webhook URL
teamsAn Adaptive Card messageMicrosoft Teams Workflows webhook
telegramPlain text, at most 4096 charactersCreated with bot_token and chat_id instead of url; the token is never shown again

Next steps