Webhooks

A webhook sends a notification to a URL you choose whenever a monitored DNS record starts passing or failing. Each of those changes is an event, either dns_record.failing or dns_record.passing, and we send it to each of your enabled webhooks as a delivery. Each delivery is a signed HTTPS request to the webhook's URL, so your own services, automation tools, and chat or push notification apps can act on DNS changes as they happen.

Each delivery carries a stable event ID and a Standard Webhooks signature. You can send a structured JSON payload, a single-key JSON payload for chat apps such as Discord and Google Chat, or a plain text payload for push notification services such as ntfy.

• Sending to a chat, push, or automation app? Add a webhook, then follow the steps for your chat or push app or automation tool.
• Building your own endpoint? Use the Envelope format, verify signatures, respond quickly, and skip duplicates by their webhook-id.

Plans and Limits

The number of webhooks you can add depends on your plan:

See our Pricing page for plan details.

The account holder and team members with the Admin role can add and manage webhooks.

Set Up a Webhook

1. Click the Account menu in the top-right corner, then click Notification Settings:

   

2. Click the Webhooks tab, then click Add webhook.
3. Enter a Name and the URL that should receive deliveries, then click Save:

   

The URL must start with https:// and include a full hostname, such as https://hooks.example.com/dnscheck. It can include a query string (the part starting with ?), but it can't contain a username and password (use a custom header instead), or a fragment (the part starting with #).

By default, a webhook sends the Envelope payload and no custom header. Click Show advanced options to choose a different payload format or to add a custom header.

After you save, we show the webhook's Signing secret, hidden until you click Show. Click Copy to copy it into your endpoint so it can verify that each delivery came from DNS Check. You can return to it anytime by editing the webhook.

Your webhooks are listed on the Webhooks tab, with each one's name, host, payload format, and whether it's enabled:

Each row's drop-down menu has these actions:

• Edit changes the webhook's settings and shows its signing secret.
• Send test event sends the webhook a sample event, so you can check that your endpoint works. See Send a Test Event.
• Roll secret replaces the webhook's signing secret and shows you the new one. See Roll the Signing Secret.
• Disable stops deliveries to the webhook, including any already waiting to be retried. Events that happen while it's disabled are never sent, not even after you enable it again. The menu item then becomes Enable, which starts deliveries again with the next event.
• Delete removes the webhook and stops its pending deliveries.

Send a Test Event

To check that your endpoint works, click the webhook's drop-down menu on the Webhooks tab, then select Send test event. We send the webhook a dns_record.failing event with sample data, so your endpoint's handling for failing records runs just as it would for a real event. To keep it from being mistaken for a real failure:

• It carries an X-DNSCheck-Test: true header.
• Its message starts with "This is a test from DNS Check."
• Its record is a sample: www.example.com. with the record ID 0 and the record group ID 00000000-0000-0000-0000-000000000000, neither of which is ever a real ID
• Its links, in the message and in the envelope's url and history_url fields, point to this section of the docs rather than to a real record.

Reload the page after a few seconds to see the test's result under Recent Deliveries, where it's marked Test:

A test is sent once and isn't retried, so fix the problem the last result points to, then send another. The option is hidden while a webhook is disabled.

When Events Are Sent

We send an event to each enabled webhook when a monitored DNS record starts failing, and another when it starts passing again. While a record keeps failing, we don't send more events for its later checks.

Webhooks follow the same rules as your other notifications. No event is sent:

• When a newly created record passes its first check
• For a record in a group whose notifications are turned off
• For a ServFail error that hasn't yet reached your ServFail notification threshold, or when the record passes again after one

So events don't always come in pairs. For example, if a record fails while its group's notifications are off, and passes after they're turned back on, you receive a passing event without a failing one before it. Treat each event as the record's current state, not as a change from the last event you received.

We send each event as soon as we detect the state change.

Chat and Push Notification Apps

For Slack, use DNS Check's Slack integration instead, which is available on every plan.

The apps below aren't part of DNS Check, and they can change how they accept webhooks at any time. If these instructions become stale, let us know.

Discord

1. In Discord, open the channel's settings (Edit Channel), click Integrations, then Create Webhook.
2. Give the Webhook a name, select a channeloo, then click Copy Webhook URL. It looks like https://discord.com/api/webhooks/1234567890/abcdEFGH....
3. In DNS Check, add a webhook with that URL. Under Show advanced options, choose Message only and set the Message key to content.

Discord rejects a payload without a content field, so the Envelope and the default text key won't work.

Google Chat

1. In Google Chat, open the space, click the space's name, then click Apps & integrations.
2. Click Add webhooks, name the webhook, save it, and copy its URL. It looks like https://chat.googleapis.com/v1/spaces/AAAA.../messages?key=...&token=....
3. In DNS Check, add a webhook with that URL. Under Show advanced options, choose Message only and leave the Message key set to text.

Google Chat rejects fields it doesn't recognize, so the Envelope format won't work. Incoming webhooks are available in Google Workspace accounts, and your Workspace administrator may need to allow them.

Mattermost and Rocket.Chat

1. In Mattermost or Rocket.Chat, create an incoming webhook for the channel, and copy its URL.
2. In DNS Check, add a webhook with that URL. Under Show advanced options, choose Message only and leave the Message key set to text.

Mattermost reads the Envelope's type field as its own message type and rejects the delivery, so the Envelope won't work there.

ntfy

ntfy sends push notifications to your phone or desktop for anything posted to a topic URL.

1. Pick a topic name that's hard to guess, and subscribe to it in the ntfy app. Anyone who knows a topic's name on ntfy.sh can read its messages.
2. In DNS Check, add a webhook with the topic's URL, such as https://ntfy.sh/dnscheck-7f3a9c2e. Under Show advanced options, choose Plain text.
3. If the topic requires an access token, set the custom header's name to Authorization and its value to Bearer followed by a space and the token.

Use Plain text rather than JSON because ntfy shows a JSON payload as-is.

Automation Tools

Automation tools can start a workflow from a webhook. The tools below give you a URL to paste into DNS Check and can read the default Envelope format, so you can use its fields, such as type and data.record.name, in later steps. To give the tool a sample to work from, send a test event once the URL is in place:

• Zapier: start a Zap with the Webhooks by Zapier app's Catch Hook trigger. Its URL starts with https://hooks.zapier.com/hooks/catch/. Webhooks by Zapier needs a paid Zapier plan.
• Make: start a scenario with the Webhooks app's Custom webhook trigger, and add a webhook to get its URL.
• n8n: start a workflow with a Webhook node, and set its HTTP method to POST. Use the node's production URL in DNS Check. Its test URL only works while the n8n editor is listening for a test event.
• IFTTT: use the Webhooks service's Receive a web request with a JSON payload trigger. The URL is https://maker.ifttt.com/trigger/event/json/with/key/key, with your event name and your Webhooks key. The Webhooks service needs IFTTT Pro.

Like the chat apps above, these tools aren't part of DNS Check and can change how they accept webhooks, or which plans include them.

Payload Formats

Every webhook has a payload format, which you choose under Show advanced options. All three carry the same message, which ends with a link to the DNS record in DNS Check:

The example.com A record in the "Web server" record group is failing: https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529

Envelope

The default, and the best choice when you're writing your own endpoint. Every format's message names the record and links to it, but only the Envelope gives your code each detail as its own field, including some the message leaves out, such as why the check failed. The payload is JSON, sent with Content-Type: application/json:

{
  "id": "evt_4f1c9a2e7b3d4c6f8a0e5b2d9c7f1a3e",
  "type": "dns_record.failing",
  "timestamp": "2026-09-15T14:05:07Z",
  "text": "The example.com A record in the \"Web server\" record group is failing: https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529",
  "data": {
    "record": {
      "id": 5529,
      "name": "example.com.",
      "record_type": "A",
      "value": "192.0.2.10",
      "status": "fail",
      "error": "Expected:\nexample.com. A 192.0.2.10\n\nFound:\nexample.com. A 198.51.100.7",
      "responding_name_server": "198.51.100.53 (ns1.example.net)",
      "url": "https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529",
      "history_url": "https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529/history"
    },
    "group": {
      "uuid": "3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93",
      "name": "Web server",
      "url": "https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93"
    }
  }
}

The record and group fields match the ones the DNS Record Monitoring API returns, except status, error, responding_name_server, and history_url, which describe this event. We may add new fields to the envelope in the future, so your endpoint should ignore fields it doesn't recognize.

For an inverted check, dns_record.failing means the unwanted record appeared.

Message Only

JSON with a single key holding the message, for chat apps that reject unrecognized fields. Enter the key in the Message key field, which defaults to text. It can be up to 64 characters of letters, numbers, spaces, and - _ . & '. With the key set to content, the payload is:

{
  "content": "The example.com A record in the \"Web server\" record group is failing: https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529"
}

Plain Text

The message alone, sent with Content-Type: text/plain; charset=utf-8, for services that use the whole request body as the message:

The example.com A record in the "Web server" record group is failing: https://www.dnscheck.co/tests/3f6b2c1e-8d4a-4b7e-9c2f-5a1d7e0b6c93/5529

Request Headers

Every delivery is an HTTPS POST with these headers:

Verify Signatures

Anyone who finds out your webhook's URL can post to it, so check each delivery's signature before acting on it. Deliveries are signed following the Standard Webhooks specification. See Verify Webhook Signatures for examples with and without a Standard Webhooks library, and for how to roll a webhook's signing secret.

Custom Header

If your endpoint expects a credential in a header, such as a bearer token or an API key, add it under Show advanced options as the webhook's custom header. We send the header's name and value exactly as you enter them, with every delivery. For example:

We never show the saved value again. When you edit the webhook, leave the value blank to keep it, or enter a new one to replace it. To remove the header, clear its name.

Headers we set ourselves, such as Content-Type, User-Agent, and the webhook- signing headers, can't be used. If you enter one of those names, the form will tell you when you save.

Basic Authentication

A URL containing a username and password, such as https://user:[email protected]/, isn't accepted. For an endpoint that uses HTTP Basic authentication, set the header name to Authorization and the value to Basic followed by a space and the base64 encoding of username:password. To encode them:

echo -n 'username:password' | base64

For a username of username and a password of password, the header value is Basic dXNlcm5hbWU6cGFzc3dvcmQ=.

Tokens in the URL

Some services, such as Discord and Google Chat, put the token in the webhook URL itself. We support these URLs without modification. When an endpoint accepts a token either in the URL or in a header, use the header: URLs are often written to the endpoint's access logs and to any proxy logs along the way, while header values usually aren't.

Delivery and Retries

Responding to a Delivery

Respond with any 2xx status code to confirm a delivery. We wait up to 3 seconds to connect and 15 seconds for a response.

We don't follow redirects, and a 3xx response is a failed delivery. The most common cause is a URL with a missing or extra trailing slash that the endpoint redirects to its preferred form, so use the exact URL your endpoint expects. Google Apps Script web apps always respond with a redirect after running, so their deliveries show as failed even though the script ran.

Retries

That window starts when the record changes state, so an endpoint that's down for a few hours receives everything from that time, each delivery within 4 hours of the endpoint coming back, and sooner after a shorter outage. One that's down for two days receives only the events from the last 24 hours of the outage; the rest ran out of time while it was unreachable.

To catch up after an outage longer than that, look up each record's current status with the DNS Record Monitoring API, using the data.record.id and data.group.uuid from earlier events, rather than waiting for its next event. The DNS Record Group Monitoring API gives a whole group's status in one request.

Repeated Failures

One failed delivery, or an afternoon of them, doesn't affect the webhook. What counts is a run of deliveries we've given up on: a response we don't retry, such as a 404, counts on its first attempt, while 5xx responses and timeouts count only once their 24 hours of retries run out. After 3 of these in a row, we email you that the webhook is failing. A failed test event doesn't count.

We disable the webhook, and email you again, when a failure meets both of these conditions:

• It's at least the 10th failure in a row.
• It comes at least 72 hours after the run's first failure.

So a burst of failures, however large, can't disable a webhook until its run has lasted 72 hours, and a webhook that only fails now and then isn't disabled until 10 deliveries in a row have failed, however long that takes.

Both emails name the webhook and the last result we got from it, so you have somewhere to start. They go to the account holder and to any team members with the Admin role, since those are the people who can edit webhooks.

The Webhooks tab flags a failing webhook with , and one disabled this way with . Once the endpoint is working again, choose Enable from its actions menu, then Send test event to confirm it. Enabling clears the failure count, and so does any successful delivery, including a test.

Duplicates and Ordering

A delivery can arrive more than once. For example, if your endpoint processes a delivery but responds after the 15-second timeout, we retry it. Every copy carries the same webhook-id header, in every payload format, so record the IDs you've processed and skip ones you've already seen. Retries stop soon after 24 hours, so keeping each ID for 2 days is enough.

Deliveries can also arrive out of order: if a dns_record.failing delivery is retried, the dns_record.passing event that followed it might arrive first. When order matters, compare the envelope's timestamp with the last one you've processed for the same data.record.id, and ignore older events. Only the Envelope format includes these fields, so use it if your endpoint keeps track of each record's state.

IP Addresses

We send deliveries from the same servers we use to query name servers. If your endpoint sits behind a firewall, allow the IPv4 and IPv6 addresses listed in the FAQ. They're also published as the A and AAAA records of nameservers.dnscheck.co, which you can look up with dig nameservers.dnscheck.co A and dig nameservers.dnscheck.co AAAA.

We don't send deliveries to private, loopback, or other non-public addresses, so the webhook hostname must resolve to a public IP address.

Recent Deliveries

The Recent Deliveries table on the Webhooks tab shows the 500 most recent deliveries across all your webhooks, along with each outcome and the result of its latest attempt. You can search them, for example by webhook name, and sort by any column. Deliveries are kept for 30 days.

Outcomes

Last Results

The Last result column shows what the latest attempt returned. An HTTP 2xx result means the delivery succeeded. Anything else points to a problem to check: