diff --git a/documentation/notifications.md b/documentation/notifications.md index 3d4995918..cef59b33b 100644 --- a/documentation/notifications.md +++ b/documentation/notifications.md @@ -1,27 +1,22 @@ # Notifications -DNSControl has build in support for notifications when changes are made. This allows you to post messages in team chat, or send emails when dns changes are made. - -Notifications are written in the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications), and is a really simple interface to implement if you want to add -new types or destinations. +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](https://github.com/containrrr/shoutrrr) library, which knows how to communicate to many different systems. Some additional services are provided natively, see the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/notifications). ## Configuration -Notifications are set up in your credentials JSON file. They will use the `notifications` key to look for keys or configuration needed for various notification types. +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" %} ```json - "r53": { - ... - }, - "gcloud": { - ... - } , +{ + "r53": {}, + "gcloud": {}, "notifications": { - "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" + "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 %} @@ -67,25 +62,62 @@ dnscontrol push --notify Successfully ran correction for **example.com[my_provider]** - CREATE foo.example.com A 1.2.3.4 ttl=86400 ``` -## Notification types +## 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: + +* [Bark](https://containrrr.dev/shoutrrr/latest/services/bark/) +* [Discord](https://containrrr.dev/shoutrrr/latest/services/discord/) +* [Email](https://containrrr.dev/shoutrrr/latest/services/email/) +* [Google Chat](https://containrrr.dev/shoutrrr/latest/services/googlechat/) +* [Gotify](https://containrrr.dev/shoutrrr/latest/services/gotify/) +* [IFTTT](https://containrrr.dev/shoutrrr/latest/services/ifttt/) +* [Join](https://containrrr.dev/shoutrrr/latest/services/join/) +* [Matrix](https://containrrr.dev/shoutrrr/latest/services/matrix/) +* [Mattermost](https://containrrr.dev/shoutrrr/latest/services/mattermost/) +* [Ntfy](https://containrrr.dev/shoutrrr/latest/services/ntfy/) +* [OpsGenie](https://containrrr.dev/shoutrrr/latest/services/opsgenie/) +* [Pushbullet](https://containrrr.dev/shoutrrr/latest/services/pushbullet/) +* [Pushover](https://containrrr.dev/shoutrrr/latest/services/pushover/) +* [Rocketchat](https://containrrr.dev/shoutrrr/latest/services/rocketchat/) +* [Slack](https://containrrr.dev/shoutrrr/latest/services/slack/) +* [Teams](https://containrrr.dev/shoutrrr/latest/services/teams/) +* [Telegram](https://containrrr.dev/shoutrrr/latest/services/telegram/) +* [Zulip Chat](https://containrrr.dev/shoutrrr/latest/services/zulip/) + +The above list is accurate as of 2024-Dec. The compete list and all configuration details are in the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/). + +Configure `shoutrrr_url` with the Shoutrrr URL to be notified. + +{% code title="creds.json" %} +```json +{ + "notifications": { + "shoutrrr_url": "discover://token@id" + } +} +``` +{% endcode %} ### Slack/Mattermost -If you want to use the Slack integration, you need to create a webhook in Slack. -Please see the [Slack documentation](https://api.slack.com/messaging/webhooks) or the [Mattermost documentation](https://developers.mattermost.com/integrate/webhooks/incoming/) +To use the Slack integration, you need to create a webhook in Slack. +Please see the [Slack documentation](https://api.slack.com/messaging/webhooks) or the [Mattermost documentation](https://docs.mattermost.com/developer/webhooks-incoming.html) Configure `slack_url` to this webhook. Mattermost works as well, as they share the same api, ### Microsoft Teams -If you want to use the Teams integration, you need to create a webhook in Teams. +To use the Teams integration, you need to create a webhook in Teams. Please see the [Teams documentation](https://docs.microsoft.com/en-us/microsoftteams/platform/webhooks-and-connectors/how-to/add-incoming-webhook#add-an-incoming-webhook-to-a-teams-channel) Configure `teams_url` to this webhook. ### Telegram -If you want to use the [Telegram](https://telegram.org/) 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](https://telegram.me/botfather), and a Chat ID by contacting [@myidbot](https://telegram.me/myidbot). +To use the [Telegram](https://telegram.org/) 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](https://telegram.me/botfather), and a Chat ID by contacting [@myidbot](https://telegram.me/myidbot). Configure `telegram_bot_token` and `telegram_chat_id` to these values. @@ -94,19 +126,3 @@ Configure `telegram_bot_token` and `telegram_chat_id` to these values. 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. - -### Shoutrrr (email, Discord, Pushover, etc.) - -DNSControl can use many other notification methods via Shoutrrr, such as email (SMTP), Discord, Pushover and others. See the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/) for a list of supported methods and configuration instructions. - -Configure `shoutrrr_url` with the Shoutrrr URL to be notified. - -## Future work - -Yes, this seems pretty limited right now in what it can do. We didn't want to add a bunch of notification types if nobody was going to use them. The good news is, it should -be really simple to add more. We gladly welcome any PRs with new notification destinations. Some easy possibilities: - -- Email -- Generic Webhooks - -Please update this documentation if you add anything.