DOCS: Shoutrrr added list of notification services

[cafferata]

The documentation for notifications has been updated with several improvements, including prioritizing Shoutrrr as the preferred notification service, renaming “notification types” to “notification services,” and providing a JSON configuration example for Shoutrrr. Additionally, the full list of available notification services was added, and the “Future work” section was removed since Shoutrrr is now implemented. The introduction was rewritten to reflect these updates, and the JSON code example was enhanced with proper syntax highlighting.

You can check out a preview of these changes online at this link. I’d love to hear your thoughts and feedback!

cc: @hmoffatt

[hmoffatt]

Good idea @cafferata . I considered adding the full list of services when I submitted the feature, but wasn't sure how much we wanted to duplicate their documentation (especially as they made add more services), but worth it I think.

Is it confusing that Slack/Mattermost and Teams are listed under both Shoutrrr and separately?

Minor bug: the section on Slack ends with a comma, possibly mid-sentence:

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

[tlimoncelli]

Brilliant!

Yes, we should do this. Let's encourage people to use Shoutrrr.

If there are any methods that are supported by both the native dnscontrol and Shoutrrr, let's mark the native one as "legacy" and recommend the Shoutrrr version in the future. (In fact, maybe in the future the native methods should just call Shoutrrr?)

[cafferata]

Good idea @cafferata . I considered adding the full list of services when I submitted the feature, but wasn't sure how much we wanted to duplicate their documentation (especially as they made add more services), but worth it I think.

Thanks, @hmoffatt, for thinking along and sharing your perspective—it’s greatly appreciated!
I realize my GitHub pull request may not have been entirely comprehensive. The greatest value I see in including the complete Shoutrrr services list is that DNSControl users can find a notification platform directly in the DNSControl documentation without needing prior knowledge of Shoutrrr.

An example of a search term that currently doesn’t work but will after merging the GitHub pull request is:

• IFTTT
• Rocketchat

This demonstrates how including the full Shoutrrr services list will make it easier for users to find relevant notification platforms directly from the DNSControl documentation.

Minor bug: the section on Slack ends with a comma, possibly mid-sentence:

Thanks for pointing that out, @hmoffatt—it’s much appreciated! However, this bug wasn’t introduced in my changes. See:

• https://docs.dnscontrol.org/advanced-features/notifications#slack-mattermost

• dnscontrol/documentation/notifications.md

  Line 77 in 0b85cf2

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

Additionally, there’s a second GitHub issue open where we’re discussing the potential removal of these sections entirely. See:

• Remove native notification services #3243

If there are any methods that are supported by both the native dnscontrol and Shoutrrr, let's mark the native one as "legacy" and recommend the Shoutrrr version in the future. (In fact, maybe in the future the native methods should just call Shoutrrr?)

Thanks for the suggestion, Tom—it’s a great idea! I propose we merge this GitHub pull request as is and continue discussing the details of your suggestion in GitHub issue #3243. Does everyone agree with this approach?

[hmoffatt]

Both sound good, in terms of improved documentation and simplified code. (You still need to support Bonfire separately I guess.)

[cafferata]

That’s what I suspect as well. Hence my open question in GitHub issue #3243 about how @tlimoncelli envisions this, given that Bonfire is specific to Stack Overflow.

[tlimoncelli]

Thanks for updating this file! I have a few minor suggestions.

One more suggestion: Change If you want to use the X integration, you need to to To use the X integration, (it is shorter and avoids using second person pronouns)

[tlimoncelli]

Suggested change

	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 services.
	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.

[tlimoncelli]

Suggested change

	For a full overview of supported methods and configuration details, refer to the [Shoutrrr documentation](https://containrrr.dev/shoutrrr/latest/services/overview/).
	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/).

[tlimoncelli]

Suggested change

DNSControl includes built-in support for notifications, enabling you to post messages in team chats or send emails whenever DNS changes occur, with the functionality implemented in the [notifications package](https://github.com/StackExchange/dnscontrol/tree/main/pkg/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](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).