Notify

Configure global notifiers that can be used by any Service.

We are running Shoutrrr 0.8, which supports sending notifications to the services listed below.

The ‘URL Fields’ go under url_fields and ‘Query/Param Props’ go under params.

Below I have used capitals in some key naming for better readability (ignore that Argus will convert that to lower-case as it shouldn’t break anything).

The lines prefixed with a # are optional vars that aren’t required.

The config for each of these is layed out in the format of

notify:
  ...
  # As many of these (below) as you like, just ensure they have unique ID's
  EXAMPLE_NOTIFY_ID:
    type: shoutrrr
    options:
#     delay: AhBmCs                             # Time to wait when a new release is found before sending this message
#     max_tries: 3                              # Maximum number of times to try sending this message until a send is successful
#     message: >-                               # Message template
#       <{{ service_url }}|{{ service_id }}> -
#       {{ version }} released{% if web_url %}
#       (<{{ web_url }}|changelog>){% endif %}
    url_fields: {}
    params: {}

where the vars available in options stay the same every time (so they’ll be ommitted below).

message templating

The message used in the Notify messages can be customised with Django-style templating courtesy of pongo2.

The default message template is <{{ service_url }}|{{ service_id }}> - {{ version }} released{% if web_url %} (<{{ web_url }}|changelog>){% endif %} , which with a service_id of ’example_service’, a service_url of ’example.com’, no web_url and the version that triggered this message being ‘1.2.3’, woud trigger a message of example_service - 1.2.3 released (example_service would be a clickable link to the service_url). If the Service had a web_url defined, then ’ (changelog)’ would appear at the end, where the ‘changelog’ text would be a clickable link to that web_url.

The vars that can be used in both the title and message templates are:

  • service_id
  • service_url
  • web_url
  • version

The default Slack message format assumes that when web_url is defined, it is a link to the services changelog. Then, in any notifications by Argus about that service, you should get a clickable ‘changelog’ button that takes you to that web_url.

For further guidance and other helpful examples on the templating used, start by looking here.

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: bark
    url_fields:
      DeviceKey: DEVICE_KEY
      Host: your_host
#     Path: /foo
#   params:
#     Badge: 0                           # Number displayed next to App icon
#     Copy: foo                          # Value to be copied
#     Group: admins                      # Group of the notification
#     Icon: https://example.com/icon.png # URL to an image
#     Scheme: http/https                 # Server protocol
#     Sound: ''                          # Fromm https://github.com/Finb/Bark/tree/master/Sounds
#     Title: Release                     # Notification title
#     URL: https://example.com           # URL to open when notification is tapped
  • As of writing, Discord Webhooks are in the format of https://discord.com/api/webhooks/WEBHOOK_ID/TOKEN (<Server Settings> - <Integrations> - <Webhooks>)

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: discord
    url_fields:
      Token: TOKEN
      WebhookID: WEBHOOK_ID
#   params:
#     Avatar: https://release-argus.io/favicons/android-chrome-512x512.png
#     Title: Release
#     Username: Argus
  • email notifications

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: smtp
    url_fields:
#     Username: NAME
#     Password: PASSWORD123
      Host: your_host
#     Port: 25
    params:
#     FromName: Argus
      FromAddress: [email protected]
      ToAddresses: [email protected],[email protected]
#     Auth: Plain                         # None/Plain/CRAMMD5/Unknown/OAuth2
#     Subject: '{{ service_id }} Release'
#     UseHTML: no
#     UseStartTLS: yes
  • Example Google Chat incoming Webhook URL https://chat.googleapis.com/v1/spaces/ FOO /messages?key= bar &token= baz

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: googlechat
    url_fields:
      Raw: chat.googleapis.com/v1/spaces/FOO/messages?key=bar&token=baz
  • Create an application on the Gotify Web UI, and use that URL with the token for the application you make.

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: gotify
    url_fields:
      Host: gotify.example.io
#     Port: 443
#     Path: sub/path          # e.g. for gotify.example.io/sub/path
      Token: TOKEN
#   params:
#     DisableTLS: no
#     Priority: 0
#     Title: Argus

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: ifttt
    url_fields:
      WebhookID: WEBHOOK_ID
    params:
      Events: event1,event2,...
#     Title: Argus
#     UseMessageAsValue: 2
#     UseTitleAsValue: 0
#     Value1:
#     Value2:
#     Value3:
  • Go to the Join Webapp
  • Select your device
  • Click Join API
  • Your deviceId is shown in the top
  • Click Show next to API Key to see your key

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: join
    url_fields:
      APIKey: KEY
    params:
      Devices: ID1,ID2,...
#     Icon: https://release-argus.io/favicons/android-chrome-512x512.png
#     Title: Argus
  • Go to the menu in the top left and navgate to <Integrations> - <Incoming Webhooks>.

Example Mattermost Webhook - https://mattermost.example.io/hooks/TOKEN

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: mattermost
    url_fields:
#     Username: Argus
      Host: mattermost.example.io
#     Port: 443
#     Path: sub/path              # e.g. for mattermost.example.io/sub/path/hooks/TOKEN
      Token: TOKEN
#     Channel: releases
#   params:
#     Icon: https://release-argus.io/favicons/android-chrome-512x512.png # url/emoji

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: ntfy
    url_fields:
#     Username: Argus
#     Password: PASS123
      Host: mattermost.example.io
#     Port: 443
      Topic: Release123
#   params:
#     Actions: ''                        # see https://docs.ntfy.sh/publish/#action-buttons
#     Attach: https://example.com        # URL of an attachment
#     Cache: yes                         # Cache messages
#     Click: https://example.com         # URL to open when notification is clicked
#     Email: name@example                # Email address for email notifications
#     Filename: ''                       # Filename for attachment
#     Firebase: yes                      # Send to Firebase
#     Icon: https://example.com/icon.png # URL to an icon
#     Priority: default                  # Priority of the notification
#     Scheme: https                      # Server protocol
#     Tags: ''                           # Comma separated list of tags that may/may not map to eemojis
#     Title: Argus                       # Title of the notification

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: matrix
    url_fields:
#     User: NAME
      Password: PASS123
      Host: matrix.example.io
#     Port: 443
#   params:
#     DisableTLS: no
#     Rooms: '!ROOM_ID,ALIAS' # Needs the quotes as `!` is a YAML special character
#     Title: Argus

Go to <Settings> - <Integrastion List> - <API>

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: opsgenie
    url_fields:
#     Host: api.opsgenie.com # e.g. api.eu.opsgenie.com for EU instances
#     Port: 443
      APIKey: API_KEY
#   params:
#     Actions: 'An action'                        # Custom actions that will be available for the alert
#     Alias: 'alias for the alert'                # Client-defined identifier of the alert
#     Description: 'Argus found a new release'    # Description field of the alert
#     Details: '{"key1": "val1", "key2": "val2"}' # Map of key-value pairs to use as custom properties of the alert
#     Entity: 'Example entity'                    # Entity field of the alert that is generally used to specify which
#                                                 # domain the Source field of the alert
#     Note: 'Note on Argus'                       # Additional note that will be added while creating the alert
#     Priority: 'P1'                              # Priority level of the alert. Possible values are P1/P2/P3/P4/P5
#     Responders: '[{"id":"4513b7ea-3b91-438f-b7e4-e3e54af9147c","type":"team"},{"name":"NOC","type":"team"}]'
#                                                 # Teams, users, escalations and schedules that the alert will be
#                                                 # routed to send
#     Source: 'Argus'                             # Source field of the alert
#     Tags: 'argus othertag'                      # Tags of the alert
#     Title: 'Argus'                              # Notification title, optionally set by the sender
#     User: 'Argus'                               # Display name of the request owner
#     VisibleTo: '[{"id":"4513b7ea-3b91-438f-b7e4-e3e54af9147c","type":"team"},{"name":"rocket_team","type":"team"}]'
#                                                 # Teams and users that the alert will become visible to without
#                                                 # sending any notification

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: pushbullet
    url_fields:
      Token: ACCESS_TOKEN
      Targets: DEVICE1,DEVICE2
#   params:
#     Title: Argus

To get your <User Key>, go to your Pushover dashboard, and view it at the top right.

You can also make an Application specific for Argus by clicking ‘Create an Application/API Token’ at the bottom of that dashboard

In the device list, the Name column is the field used to refer to your devices

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: pushover
    url_fields:
      Token: TOKEN
      User: USER_KEY # User Key OR API Token/Key
#   params:
#     Devices: 'device1,device2'
#     Priority: 0
#     Title: Argus

Example URL username@host:port/TOKEN_A/TOKEN_B/CHANNEL

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: rocketchat
    url_fields:
#     Username: foo
      Host: rocketchat.example.io
#     Port: 443
#     Path: sub/path          # e.g. for rocketchat.example.io/sub/path
      TokenA: TOKEN_A
      TokenB: TOKEN_B
      Channel: CHANNEL

Either a Webhook, or the Slack Bot API can be used.

To get a token for a Bot:

  • Create an App for your bot with Slacks ‘Creating an app’ guide.
  • Install the App into your workspace (Slack docs).
  • From Apps, select your App and go to ‘OAuth & Permissions’
  • Copy the ‘Bot User OAuth Token’
  • e.g. `xoxb:012345678901-0123456789012-phq24qfrhqnm2mtmz54dwkop

To use Webhooks:

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: slack
    url_fields:
      Token: 'xoxb:012345678901-0123456789012-phq24qfrhqnm2mtmz54dwkop'
      Channel: argus
#   params:
#     BotName: Argus
#     Color: ''                                                          # Message left-hand border color
#     Icon: https://release-argus.io/favicons/android-chrome-512x512.png # URL or Emoji to use
#     Title: Release                                                     # Prepended text above the message

Example URL https://<organization>.webhook.office.com/webhookb2/<Group>@<Tenant>/IncomingWebhook/<AltId>/<GroupOwner>

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: teams
    url_fields:
      Group: GROUP
      Tenant: TENANT
      AltID: ALT_ID
      GroupOwner: GROUP_OWNER
    params:
#     Color: ''
      Host: example.webhook.office.com
#     Title: ''
  • To get a token, talk to the botfather.
  • Chats
    • @channel-name can only be used for public channels. The name can be found by going to Channel info, just replace the t.me/ prefix with an @.
    • chat_id is required for private channels/group chats/private chats. To get the ID, you can forward a message (from the target chat) to @UserInfoBot or @JsonDumpBot and view it at Id and message.forward_from_chat.id from those bots respectively.
    • (The above bots are created and hosted by @nadam and their sources are available to view at nadam/userinfobot and nadam/jsondumpbot)

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: telegram
    url_fields:
      Token: TOKEN_FROM_BOTFATHER
    params:
      Chats: '@channel-name,@other-channel,chat_id'
#     Notification: yes                     # No will send the message silently
#     ParseMode: None                       # None/Markdown/HTML/MarkdownV2
#     Preview: yes                          # Whether to display web page previews for URLs in the message
#     Title: Argus

Zulip Chat

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: zulip
    url_fields:
      BotMail: [email protected]
      BotKey: BOT_KEY
      Host: zulip.example.io
#   params:
#     Stream: 'mystream'
#     Topic: 'Argus'

Shoutrrr will expect the full Shoutrrr URL and so could be used for any of the services in the Shoutrrr v0.6 docs. Any params specified in params will also be passed.

Shoutrrr docs

notify:
  ...
  # as many of these (below) as you like, just ensure they have unique ID's.
  EXAMPLE_NOTIFY:
    type: shoutrrr
    url_fields:
      raw: matrix://user:password@host:port/?rooms=!roomID1,roomAlias2&disableTLS=yes

Last modified February 24, 2024: docs(0.16.0): some env vars in config (#58) (361d73a)