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.

• 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? Add a webhook, then use the Envelope format, verify signatures, respond quickly, and skip duplicates by their webhook-id. The Webhook Reference covers payloads, headers, and retries.
• Deliveries failing? Find the delivery in the Recent Deliveries table, then look up its outcome and last result.

Plans and Limits

Webhooks are available on Enterprise plans: up to 5 webhooks on Enterprise, 10 on Enterprise x2, and 15 on Enterprise x3. Basic and Professional plans don't include webhooks.

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 envelope version, 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., whose IDs are never real ones.
• Its links point to this section of the docs rather than to a real record: in the message, and in the envelope's web_url (url in version 1) and history_url fields. Its api_url fields use the sample IDs, so following them gets a 404 with the code not_found.

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.

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.

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 channel, 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.dns_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.

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.

For when we retry a delivery or disable a failing webhook, see Retries and Repeated Failures.

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: