dnscontrol/documentation/advanced-features/notifications.md

Notifications

DNSControl's "notifications" feature will log push changes to other services in real time. Typically this is used to automatically announce DNS changes in a team chatroom. The functionality is implemented using the open source Shoutrrr library, which knows how to communicate to many different systems. Some additional services are provided natively, see the notifications package.

Configuration

Notifications are configured in the creds.json file, since they often contain API keys or other secrets. The notifications key lists the notification service and options.

{% code title="creds.json" %}

{
  "r53": {},
  "gcloud": {},
  "notifications": {
    "notify_on_push": false,
    "notify_on_preview": false,
    "slack_url": "https://api.slack.com/apps/0XXX0X0XX0/incoming-webhooks",
    "teams_url": "https://outlook.office.com/webhook/00000000-0000-0000-0000-000000000000@00000000-0000-0000-0000-000000000000/IncomingWebhook/00000000000000000000000000000000/00000000-0000-0000-0000-000000000000",
    "shoutrrr_url": "discover://token@id"
  }
}

{% endcode %}

Usage

There are two ways to enable notifications:

1. On-demand: Add the --notify flag to dnscontrol preview or dnscontrol push commands
2. Automatic: Enable notify_on_push or notify_on_preview in your creds.json

Automatic notifications

To automatically send notifications without using the --notify flag, configure these options in your creds.json:

• notify_on_push: Set to true to send notifications during dnscontrol push (when changes are applied)
• notify_on_preview: Set to true to send notifications during dnscontrol preview (dry-run mode)

Example: Notifications only for actual changes (push)

{% code title="creds.json" %}

{
  "notifications": {
    "notify_on_push": true,
    "notify_on_preview": false,
    "slack_url": "https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
  }
}

{% endcode %}

Example: Notifications for both preview and push

{% code title="creds.json" %}

{
  "notifications": {
    "notify_on_push": true,
    "notify_on_preview": true,
    "teams_url": "https://outlook.office.com/webhook/..."
  }
}

{% endcode %}

With automatic notifications enabled, you don't need to use the --notify flag. The --notify flag will still work to send notifications on-demand regardless of these settings.

Example DNS change

Below is an example where we add the A record foo and display the notification output.

{% code title="dnsconfig.js" %}

D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
+ A("foo", "1.2.3.4"),
);

{% endcode %}

Preview example

Preview notifications show what changes would be made without applying them:

{% tabs %}

{% tab title="With --notify flag" %}

dnscontrol preview --notify

{% endtab %}

{% tab title="Automatically" %}

# Requires notify_on_preview: true in creds.json
dnscontrol preview

{% endtab %}

{% endtabs %}

The notification output

**Preview: example.com[my_provider] -** CREATE foo.example.com A (1.2.3.4 ttl=86400)

Push example

Push notifications show the actual changes being applied:

{% tabs %}

{% tab title="With --notify flag" %}

dnscontrol push --notify

{% endtab %}

{% tab title="Automatically" %}

# Requires notify_on_push: true in creds.json
dnscontrol push

{% endtab %}

{% endtabs %}

The notification output

Successfully ran correction for **example.com[my_provider]** - CREATE foo.example.com A 1.2.3.4 ttl=86400

Notification services

Shoutrrr

DNSControl supports various notification methods via Shoutrrr, including email (SMTP), Discord, Pushover, and many others. For detailed setup instructions, click on the desired service:

Chat and Messaging Platforms

• Discord
• Google Chat (formerly Hangouts)
• Lark
• Matrix
• Mattermost
• Rocket.Chat
• Signal
• Slack
• Teams
• Telegram
• WeCom
• Zulip

Push Notification Services

• Bark
• Gotify
• IFTTT
• Join
• Ntfy
• Pushbullet
• Pushover

Incident and Alert Management

• OpsGenie
• PagerDuty

Email Services

• SMTP

Specialized Services

• Generic
• Notifiarr

Configure shoutrrr_url with the Shoutrrr URL to be notified.

{% code title="creds.json" %}

{
  "notifications": {
    "shoutrrr_url": "discover://token@id"
  }
}

{% endcode %}

Slack/Mattermost

To use the Slack integration, you need to create a webhook in Slack. Please see the Slack documentation or the Mattermost documentation

Configure slack_url to this webhook. Mattermost works as well, as they share the same api,

Microsoft Teams

To use the Teams integration, you need to create a webhook in Teams. Please see the Teams documentation

Configure teams_url to this webhook.

Telegram

To use the Telegram integration, you need to create a Telegram bot and obtain a Bot Token, as well as a Chat ID. Get a Bot Token by contacting @BotFather, and a Chat ID by contacting @myidbot.

Configure telegram_bot_token and telegram_chat_id to these values.

Bonfire

This is Stack Overflow's built in chat system. This is probably not useful for most people.

Configure bonfire_url to be the full url including room and api key.