github.com/StackExchange/dnscontrol/v4@v4.11.0/documentation/notifications.md (about)

     1  # Notifications
     2  
     3  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.
     4  
     5  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
     6  new types or destinations.
     7  
     8  ## Configuration
     9  
    10  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.
    11  
    12  {% code title="creds.json" %}
    13  ```json
    14    "r53": {
    15        ...
    16      },
    17    "gcloud": {
    18          ...
    19    } ,
    20    "notifications": {
    21        "slack_url": "https://api.slack.com/apps/0XXX0X0XX0/incoming-webhooks",
    22        "teams_url": "https://outlook.office.com/webhook/00000000-0000-0000-0000-000000000000@00000000-0000-0000-0000-000000000000/IncomingWebhook/00000000000000000000000000000000/00000000-0000-0000-0000-000000000000"
    23    }
    24  ```
    25  {% endcode %}
    26  
    27  ## Usage
    28  
    29  If you want to send a notification, add the `--notify` flag to the `dnscontrol preview` or `dnscontrol push` commands.
    30  
    31  Below is an example where we add [the A record](language-reference/domain-modifiers/A.md) `foo` and display the notification output.
    32  
    33  {% code title="dnsconfig.js" %}
    34  ```diff
    35  D("example.com", REG_MY_PROVIDER, DnsProvider(DSP_MY_PROVIDER),
    36  + A("foo", "1.2.3.4"),
    37  END);
    38  ```
    39  {% endcode %}
    40  
    41  ### Preview example
    42  
    43  In case of `dnscontrol preview`:
    44  
    45  ```shell
    46  dnscontrol preview --notify
    47  ```
    48  
    49  **The notification output**
    50  
    51  ```shell
    52  **Preview: example.com[my_provider] -** CREATE foo.example.com A (1.2.3.4 ttl=86400)
    53  ```
    54  
    55  ### Push example
    56  
    57  In case of `dnscontrol push`:
    58  
    59  ```shell
    60  dnscontrol push --notify
    61  ```
    62  
    63  **The notification output**
    64  
    65  ```shell
    66  Successfully ran correction for **example.com[my_provider]** - CREATE foo.example.com A 1.2.3.4 ttl=86400
    67  ```
    68  
    69  ## Notification types
    70  
    71  ### Slack/Mattermost
    72  
    73  If you want to use the Slack integration, you need to create a webhook in Slack.
    74  Please see the [Slack documentation](https://api.slack.com/messaging/webhooks) or the [Mattermost documentation](https://docs.mattermost.com/developer/webhooks-incoming.html)
    75  
    76  Configure `slack_url` to this webhook. Mattermost works as well, as they share the same api,
    77  
    78  ### Microsoft Teams
    79  
    80  If you want to use the Teams integration, you need to create a webhook in Teams.
    81  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)
    82  
    83  Configure `teams_url` to this webhook.
    84  
    85  ### Telegram
    86  
    87  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).
    88  
    89  Configure `telegram_bot_token` and `telegram_chat_id` to these values.
    90  
    91  ### Bonfire
    92  
    93  This is Stack Overflow's built in chat system. This is probably not useful for most people.
    94  
    95  Configure `bonfire_url` to be the full url including room and api key.
    96  
    97  ## Future work
    98  
    99  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
   100  be really simple to add more. We gladly welcome any PRs with new notification destinations. Some easy possibilities:
   101  
   102  - Email
   103  - Generic Webhooks
   104  
   105  Please update this documentation if you add anything.