Webhooks & Alerts
Contents
PrimeDNS can tell you when something happens to your DNS: a record is changed or deleted, a CNAME stops pointing at anything, the name servers of your domain change, resolvers start returning errors, a certificate is about to expire. This guide shows how to choose where those messages go (e-mail, Slack, Discord, Microsoft Teams, Telegram, or your own server), how to create the rules that trigger them, and how to test the whole chain before you rely on it.

Two things work together, and both live under Notifications in the panel:
- Where to be told: e-mail (always available) and the endpoints you add on the Webhooks & chat tab.
- What to be told about: the alert rules. A rule watches one thing and notifies by e-mail, through an endpoint, or both.
The quickest start: add one endpoint (section 2), create one rule (section 3), press Send test (section 4).
Why set this up
DNS usually works silently until the day it does not, and the damage is done before anyone looks. A notification turns "a customer told us" into "we knew within minutes". These are the situations the rules are made for:
| Situation | Rule | What you get |
|---|---|---|
| A colleague, a script or an attacker changes or deletes an NS, MX or other record, and mail or the website quietly breaks. | record_changed |
A message with the old and new value and who or what changed it, so you can undo it at once. Together with Team & RBAC you can also limit who may change records at all. |
| You shut down a service (an old app, a storage bucket, a landing page) and forgot the CNAME that points to it. Someone else can claim that name and serve content on your subdomain. | dangling_cname |
A message naming the CNAME and the missing target, so you remove it before it is abused. |
| A domain is moved, transferred or hijacked at the registrar, and the name servers it uses are no longer yours. | delegation_changed |
A message with the previous and the new name servers. Your own zone shows nothing, because the change happens above it. |
| Users cannot resolve your names, or someone is hammering a zone. | servfail_pct, nxdomain_pct, spike_event, no_queries |
An early signal from the answers your zones actually give, instead of a ticket from a user. |
| A certificate expires and a site shows a browser warning. | ssl_expiring |
A message days before, while there is still time to renew. |
| Several people manage the same DNS and nobody sees what the others do. | record_changed to a shared channel |
Every change lands in the team channel, in the place where people already talk. |
| A home or office address is kept up to date by a DynDNS client and you want to know when it changes. | the ddns.updated event |
A message with the old and new address each time the client updates it. |
| You want to react automatically: open a ticket, page the on-call person, start a pipeline. | any event to your own server | A signed JSON request your code can act on. |
The Audit Log keeps the full history to read afterwards. Notifications are the part that tells you now, without anyone having to look.
1. E-mail
There is nothing to set up. Alert rules write to the e-mail address of your account. To change that address, edit your profile under Account. Whether a rule sends e-mail is decided by its E-mail switch when you create it.

Open the E-mail tab and press Send a test e-mail to check that mail reaches you (look in the spam folder if it does not arrive within a minute). The same tab lists the rules that e-mail you. A test can be sent once every 30 seconds.
2. Add an endpoint: Slack, Discord, Teams, Telegram or your own server
On the Webhooks & chat tab, choose Send to. The form then shows the steps and the fields for that
service. Give the endpoint a name (for example #dns-alerts), keep the events you want, and press + Add endpoint.

Slack
- Create (or open) a Slack app for your workspace and switch on Incoming Webhooks in its settings.
- Click Add New Webhook to Workspace, choose the channel and authorize.
- Copy the Webhook URL, which starts with
https://hooks.slack.com/services/, into the Webhook URL field.
Treat that URL as a secret: anyone who has it can post to your channel. Slack describes the steps in its incoming webhooks documentation.
Discord
- Open the settings of the channel that should receive the messages, then Integrations and Webhooks.
- Create a webhook and copy its URL, which starts with
https://discord.com/api/webhooks/, into the Webhook URL field.
Messages never ping anybody: mentions such as @everyone are switched off. See the Discord webhook documentation.
Microsoft Teams
Microsoft retired the old Office 365 connectors in May 2026, so Teams uses a Workflows webhook:
- In Teams open the channel menu (...) and choose Workflows.
- Pick the template Send webhook alerts to a channel, set it up and save.
- Copy the webhook link the workflow shows into the Webhook URL field.
See Microsoft's documentation.
Telegram
Telegram needs two things: a bot token and the id of the chat that should receive the messages.

- Open @BotFather in Telegram, send
/newbotand follow the questions. It gives you the bot token, which looks like123456789:AA.... - Open a chat with your new bot and press Start. To use a group instead, add the bot to the group. For a channel, add the bot as an administrator that may post.
- Find the chat id. Send the bot any message, then open this address in a browser (with your token) and look for
"chat":{"id": ...}:
A private chat has a positive number, a group a negative one (for examplehttps://api.telegram.org/bot<your token>/getUpdates-1001234567890). A public channel can be given as@channelname. - Choose Telegram in Send to, paste the token and the chat id, and add the endpoint.
PrimeDNS keeps the token to send the messages and never shows it again: the list shows bot123456789:***.
If the token leaks, revoke it in @BotFather and add the endpoint again with the new one. More in Telegram's
bot documentation.
Your own server (signed JSON)
Choose Your own server to receive the event as JSON on a URL you control. Every request is signed so you can check it came from PrimeDNS. Leave Signing secret empty and one is generated for you.
POST /your-hook HTTP/1.1
Content-Type: application/json
X-Webhook-Event: record.updated
X-Webhook-Signature: sha256=<hex digest>
X-Webhook-Timestamp: 1758500000
X-Webhook-Delivery: <delivery id>
X-Webhook-Event-Id: <event id>
{
"id": "3f6c1e0a-7d8b-4b7e-9c1a-2f3e4d5c6b7a",
"version": 1,
"event": "record.updated",
"account_id": 139111,
"timestamp": "2026-10-30T10:15:30Z",
"data": {
"record": { "name": "www.example.com", "type": "A", "content": "192.0.2.11", "ttl": 300 },
"old": { "name": "www.example.com", "type": "A", "content": "192.0.2.10", "ttl": 300 }
}
}
The signature is an HMAC-SHA256 over {timestamp}.{raw body} with your secret. Verify it before you trust the payload:
// Node.js
const crypto = require('crypto');
function isValid(rawBody, timestamp, signatureHeader, secret) {
const expected = 'sha256=' + crypto
.createHmac('sha256', secret)
.update(`${timestamp}.${rawBody}`)
.digest('hex');
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader));
}
# PHP
$sigPayload = $timestamp . '.' . $rawBody;
$expected = 'sha256=' . hash_hmac('sha256', $sigPayload, $secret);
if (!hash_equals($expected, $signatureHeader)) {
http_response_code(401);
exit;
}
X-Webhook-Event-Id to ignore a delivery you already handled: it is the same on every retry.
Which events an endpoint receives
| Event | When |
|---|---|
alert.fired | One of your alert rules triggered (section 3). This is what the chat endpoints need. |
record.created, record.updated, record.deleted | A DNS record was added, changed (with the previous values in old) or removed. |
ddns.updated | A DynDNS client changed the address of a dynamic host. |
zone.created, zone.deleted | A zone was added or removed. |
dnssec.enabled, dnssec.disabled | DNSSEC was switched on or off for a zone. |
apikey.created, apikey.revoked | An API key was created or revoked. |
team.member_added, team.member_removed | Someone joined or left your team. |
zone.imported | A zone file was imported (one notice per import, not per record). |
template.applied, view.changed | A template was applied to a zone, or a split-horizon view changed. |
domain.registered, domain.renewed, domain.transfer_requested | A domain was registered, renewed or a transfer was ordered. |
ssl.requested, ssl.renewed, ssl.deleted | A certificate was ordered, renewed or deleted. |
team.invited, team.role_changed, apikey.updated | An invitation was sent, a member's role changed, or an API key was edited. |
account.password_changed, account.totp_enabled, account.totp_disabled, account.totp_recovery_regenerated, account.passkey_added, account.passkey_removed, account.profile_updated | Sign-in security or profile changed. Worth sending to a channel the whole team sees. |
webhook.created, webhook.deleted | A notification endpoint was added or removed (the URL is never included). |
ssl.expiring | A monitored certificate is close to expiry. |
Notices about changes made by a person (the team, key, domain, certificate, view and account events) say who did it and whether it came from the panel or an API key. An existing endpoint only receives the events ticked on it, so open it and tick the new ones you want.
A chat endpoint can listen to any of them: each one arrives as a short readable message. Keep only alert.fired ticked if you want
the channel to stay quiet except for alerts.
3. Create an alert rule
On the Alert Rules tab choose what to watch under Alert me when. The form explains the chosen type and hides the fields it does not use. Leave Zone empty to cover all your zones. Under Notify through choose all my endpoints that take alerts, no endpoint (e-mail only) or one endpoint, and keep or clear also e-mail me.

| Type | Alerts when | Threshold |
|---|---|---|
record_changed | A record is added, changed or deleted in your zones. The alert shows the old and new value and who did it. Limit it with Record types, for example NS,MX. DynDNS updates are not included (they have their own ddns.updated event). | none |
dangling_cname | A CNAME points at a name that no longer exists, which is a subdomain takeover risk. A target must be missing on two checks about half an hour apart before you are told, so a short hiccup does not alert. | none |
delegation_changed | The name servers your domain has at its registry change, for example after a transfer or a hijack. Checked about hourly; a change has to be seen twice before you are told. | none |
servfail_pct | At least the threshold percent of answers for your zone are SERVFAIL within the window. | percent |
nxdomain_pct | At least the threshold percent of answers are NXDOMAIN within the window. | percent |
spike_event | The queries in the window are at least threshold times the queries in the window before (empty means 3). | times |
no_queries | A zone received no queries at all within the window. Needs a zone. | none |
ssl_expiring | A certificate on the SSL Monitors tab is within the number of days that monitor has set as its own alert days before. | any number |
Examples
- Tell me when anyone touches NS or MX. Type Record changed, Zone empty, Record types
NS,MX, Notify through your Slack endpoint. Every change to a name server or mail record in any zone shows up in the channel with the before and after value and the name of whoever made it. - Catch forgotten CNAMEs. Type Dangling CNAME, Zone empty, e-mail on. You are told when a CNAME in any of your zones points at a service that was shut down.
- Notice a hijacked or moved domain. Type Delegation changed, Zone
example.com, Notify through Telegram. You are told when the name servers at the registry stop being the ones you expect. - Resolver trouble. Type SERVFAIL %, Threshold
5, Window15: alert when 5 percent or more of the answers in the last 15 minutes were SERVFAIL.
What an alert looks like in a chat (Slack shown; Discord, Teams and Telegram carry the same text):
DNS record changed in example.com
• update example.com MX: 10 mail.old.example -> 10 mail.new.example by jan (web)
2026-10-30T10:15:30Z
4. Test it
Test before you rely on it:
- Send test next to an endpoint sends a short test message to it.
- Send test next to an alert rule sends a made-up alert through exactly the channels that rule uses (e-mail and the endpoint you chose). It is marked TEST, no incident is created, and the findings are invented. One test per rule every 30 seconds.
- The Last deliveries column on the endpoint list shows the result: the status of the last three deliveries, the HTTP code the receiver answered and the time.
Messages are sent within about a minute. If a test does not arrive, see the next section.
5. If a message does not arrive
| You see | What it usually means |
|---|---|
Status pending | Still queued; messages go out within about a minute. |
Status failed with an HTTP code | The receiver answered with an error. We retry: five attempts after 1 minute, 5 minutes, 30 minutes and 2 hours, then the delivery is marked abandoned. |
| HTTP 400, 403 or 404 from Slack, Discord or Teams | The URL is wrong, was deleted or revoked, or the channel or workflow no longer exists. Create the webhook again in the service and replace the endpoint. |
| HTTP 401 from Telegram | The bot token is wrong or was revoked. Create the endpoint again with a valid token. |
| HTTP 400 or 403 from Telegram | The chat id is wrong, or the bot cannot write there: press Start in the bot chat, add the bot to the group, or make it an administrator of the channel. |
| Your own server: 401 from your code | The signature check fails. Hash the raw body with {timestamp}.{body} and the secret shown when you created the endpoint. |
| No e-mail | Check the spam folder, use Send a test e-mail, and make sure the rule has also e-mail me ticked. |
Long messages are shortened to what each service allows (for example 2000 characters for Discord), with a line saying how many lines were left out. The number of endpoints and alert rules you can have depends on your plan; see Pricing.
6. The same through the API
Everything in the panel is also available through the API. Examples with a key that has the webhooks:write and alerts:write scopes:
# Slack endpoint
curl -X POST https://api.primedns.net/v1/webhooks \
-H "Authorization: Bearer $PRIMEDNS_KEY" -H "Content-Type: application/json" \
-d '{"name": "#dns-alerts", "format": "slack",
"url": "https://hooks.slack.com/services/T000/B000/XXXX",
"events": ["alert.fired"]}'
# Telegram endpoint: a token and a chat id instead of a url
curl -X POST https://api.primedns.net/v1/webhooks \
-H "Authorization: Bearer $PRIMEDNS_KEY" -H "Content-Type: application/json" \
-d '{"name": "DNS alerts", "format": "telegram",
"bot_token": "123456789:AA...", "chat_id": "-1001234567890",
"events": ["alert.fired"]}'
The answer contains the webhook id. Formats are generic (the default), slack, discord, teams and telegram. Then a rule that uses it:
# Alert on every change to NS or MX records, in any zone, to that webhook
curl -X POST https://api.primedns.net/v1/alert-rules \
-H "Authorization: Bearer $PRIMEDNS_KEY" -H "Content-Type: application/json" \
-d '{"name": "NS and MX changes", "rule_type": "record_changed",
"record_types": "NS,MX", "webhook_id": 42, "notify_email": true}'
# Send a made-up alert through that rule's channels
curl -X POST https://api.primedns.net/v1/alert-rules/17/test \
-H "Authorization: Bearer $PRIMEDNS_KEY"
# A test e-mail to the account address
curl -X POST https://api.primedns.net/v1/notifications/test-email \
-H "Authorization: Bearer $PRIMEDNS_KEY"
# What happened to the deliveries of a webhook
curl https://api.primedns.net/v1/webhooks/42/deliveries \
-H "Authorization: Bearer $PRIMEDNS_KEY"
webhook_id sends that rule only to that endpoint; leave it out to use every endpoint that takes alert.fired, and set
notify_webhook to false for e-mail only. The rule types are the ones in the table above. The full reference is in the
API documentation.
Next steps
- Combine
ssl_expiringalerts with the SSL Monitors tab to hear about a certificate before it lapses, not after. - Read who changed what, after the fact, in the Audit Log, and limit who can change it in Team & RBAC.