NAME

SYNOPSIS

DESCRIPTION

You can enable one or more additional reporters that are used to send change notifications. Please note that most reporters need additional dependencies installed.

See urlwatch-config(5) for generic config settings.

To send a test notification, use the --test-reporter command-line option with the name of the reporter:

urlwatch --test-reporter stdout

This will create a test report with new, changed, unchanged and error notifications (only the ones configured in display in the configuration will be shown in the report) and send it via the stdout reporter (if it is enabled).

To test if your e-mail reporter is configured correctly, you can use:

urlwatch --test-reporter email

Any reporter that is configured and enabled can be tested.

If the notification does not work, check your configuration and/or add the --verbose command-line option to show detailed debug logs.

BUILT-IN REPORTERS

urlwatch --features

At the moment, the following reporters are built-in:

PUSHOVER

You can send to a specific device by using the device name, as indicated when you add or view your list of devices in the Pushover console. For example device: 'MyPhone', or device: 'MyLaptop'. To send to all of your devices, set device: null in your config (urlwatch --edit-config) or leave out the device configuration completely.

Setting the priority is possible via the priority config option, which can be lowest, low, normal, high or emergency. Any other setting (including leaving the option unset) maps to normal.

PUSHBULLET

TELEGRAM

telegram:
  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token
  chat_id: '88888888' # the chat id where the messages should be sent
  enabled: true

Messages can be sent silently (silent) if you prefer notifications with no sounds, and monospace formatted (monospace). By default notifications are not silent and no formatting is done.

telegram:
  # ...
  silent: true # message is sent silently
  monospace: true # display message as pre-formatted code block

To set up Telegram, from your Telegram app, chat up BotFather (New Message, Search, “BotFather”), then say /newbot and follow the instructions. Eventually it will tell you the bot token (in the form seen above, <number>:<random string>) - add this to your config file.

You can then click on the link of your bot, which will send the message /start. At this point, you can use the command urlwatch --telegram-chats to list the private chats the bot is involved with. This is the chat ID that you need to put into the config file as chat_id. You may add multiple chat IDs as a YAML list:

telegram:
  bot_token: '999999999:3tOhy2CuZE0pTaCtszRfKpnagOG8IQbP5gf' # your bot api token
  chat_id:
    - '11111111'
    - '22222222'
  enabled: true

Don’t forget to also enable the reporter.

SLACK

slack:
  webhook_url: 'https://hooks.slack.com/services/T50TXXXXXU/BDVYYYYYYY/PWTqwyFM7CcCfGnNzdyDYZ'
  enabled: true

To set up Slack, from you Slack Team, create a new app and activate “Incoming Webhooks” on a channel, you’ll get a webhook URL, copy it into the configuration as seen above.

MATTERMOST

mattermost:
  webhook_url: 'http://{your-mattermost-site}/hooks/XXXXXXXXXXXXXXXXXXXXXX'
  enabled: true

See Incoming Webooks <https://developers.mattermost.com/integrate/incoming-webhooks/> in the Mattermost documentation for details.

DISCORD

discord:
   webhook_url: 'https://discordapp.com/api/webhooks/11111XXXXXXXXXXX/BBBBYYYYYYYYYYYYYYYYYYYYYYYyyyYYYYYYYYYYYYYY'
   enabled: true
   embed: true
   colored: true
   subject: '{count} changes: {jobs}'

To set up Discord, from your Discord Server settings, select Integration and then create a "New Webhook", give the webhook a name to post under, select a channel, push "Copy Webhook URL" and paste it into the configuration as seen above.

Embedded content might be easier to read and identify individual reports. Subject preceeds the embedded report and is only used when embed is true.

When colored is true reports will be embedded in code section (with diff syntax) to enable colors.

IFTTT

https://ifttt.com/maker_webhooks/settings

The URL shown in "Account Info" has the following format:

https://maker.ifttt.com/use/{key}

In this URL, {key} is your API key. The configuration should look like this (you can pick any event name you want):

ifttt:
  enabled: true
  key: aA12abC3D456efgHIjkl7m
  event: event_name_you_want

The event will contain three values in the posted JSON:

These values will be passed on to the Action in your Recipe.

MATRIX

To achieve this, you first need to register a Matrix account for the bot on any homeserver.

You then need to acquire an access token and room ID, using the following instructions adapted from this guide <https://t2bot.io/docs/access_tokens/>:

Here is a sample configuration:

matrix:
  homeserver: https://matrix.org
  access_token: "YOUR_TOKEN_HERE"
  room_id: "!roomroomroom:matrix.org"
  enabled: true

You will probably want to use the following configuration for the markdown reporter, if you intend to post change notifications to a public Matrix room, as the messages quickly become noisy:

markdown:
  details: false
  footer: false
  minimal: true
  enabled: true

E-MAIL VIA GMAIL SMTP

You do not want to do this with your primary GMail account, but rather on a separate account that you create just for sending mails via urlwatch. Allowing less secure apps and storing the password (even if it's in the keychain) is not good security practice for your primary account.

Now, start the configuration editor:

urlwatch --edit-config

These are the keys you need to configure:

report:
  email:
    enabled: true
    from: your.username@gmail.com
    to: your.destination.email@example.com
    method: smtp
    smtp:
      host: smtp.gmail.com
      auth: true
      port: 587
      starttls: true

The password is best stored in your keychain, and not in the config file. To store the password, run:

urlwatch --smtp-login

This will query your password, check the login, and store it in your keychain. Subsequent runs will use this password for logging in.

E-MAIL VIA AMAZON SIMPLE E-MAIL SERVICE (SES)

SMTP LOGIN WITHOUT KEYRING

report:
  email:
    smtp:
      auth: true
      insecure_password: secret123

The insecure_password key will be preferred over the data stored in the keyring. Please note that as the name says, storing the password as plaintext in the configuration is insecure and bad practice, but for an e-mail account that’s only dedicated for sending mails this might be a way. Never ever use this with your your primary e-mail account! Seriously! Create a throw-away GMail (or other) account just for sending out those e-mails or use local sendmail with a mail server configured instead of relying on SMTP and password auth.

Note that this makes it really easy for your password to be picked up by software running on your machine, by other users logged into the system and/or for the password to appear in log files accidentally.

XMPP

To achieve this, you should register a new XMPP account that is just used for urlwatch.

Here is a sample configuration:

xmpp:
  enabled: true
  sender: "BOT_ACCOUNT_NAME"
  recipient: "YOUR_ACCOUNT_NAME"

The password is not stored in the config file, but in your keychain. To store the password, run: urlwatch --xmpp-login and enter your password.

If for whatever reason you cannot use a keyring to store your password you can also set the insecure_password option in the XMPP config. For more information about the security implications, see SMTP login without keyring.

PROWL

To achieve this, you should register a new Prowl account, and have the Prowl application installed on your iOS device.

To create an API key for urlwatch:

Here is a sample configuration:

prowl:
  enabled: true
  api_key: '<your api key here>'
  priority: 2
  application: 'urlwatch example'
  subject: '{count} changes: {jobs}'

The “subject" field is similar to the subject field in the email, and will be used as the name of the Prowl event. The application is prepended to the event and shown as the source of the event in the Prowl App.

FILES

SEE ALSO

COPYRIGHT