Provided by: urlwatch_2.28-3_all bug

NAME

       urlwatch-reporters - Reporters for change notifications

SYNOPSIS

       urlwatch --edit-config

DESCRIPTION

       By  default  urlwatch(1) prints out information about changes to standard output, which is
       your terminal if you run it interactively. If running via  cron(8)  or  another  scheduler
       service, it depends on how the scheduler is configured.

       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

       The list of built-in reporters can be retrieved using:

          urlwatch --features

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

       • discord: Send a message to a Discord channel

       • email: Send summary via e-mail / SMTP

       • ifttt: Send summary via IFTTT

       • mailgun: Send e-mail via the Mailgun service

       • matrix: Send a message to a room using the Matrix protocol

       • mattermost: Send a message to a Mattermost channel

       • prowl: Send a detailed notification via prowlapp.com

       • pushbullet: Send summary via pushbullet.com

       • pushover: Send summary via pushover.net

       • shell: Pipe a message to a shell command

       • slack: Send a message to a Slack channel

       • stdout: Print summary on stdout (the console)

       • telegram: Send a message using Telegram

       • xmpp: Send a message using the XMPP Protocol

PUSHOVER

       You can configure urlwatch to send real time  notifications  about  changes  via  Pushover
       <https://pushover.net/>.  To  enable  this,  ensure  you  have  the  chump  python package
       installed (see Dependencies). Then edit your config (urlwatch  --edit-config)  and  enable
       pushover.  You will also need to add to the config your Pushover user key and a unique app
       key (generated by  registering  urlwatch  as  an  application  on  your  Pushover  account
       <https://pushover.net/apps/build>.

       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

       Pushbullet notifications are configured similarly to Pushover (see above). You’ll need  to
       add   to   the   config   your   Pushbullet  Access  Token,  which  you  can  generate  at
       https://www.pushbullet.com/#settings

TELEGRAM

       Telegram notifications are configured using the Telegram Bot API. For this, you’ll need  a
       Bot API token and a chat id (see https://core.telegram.org/bots). Sample configuration:

          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  notifications  are  configured  using  “Slack  Incoming Webhooks”. Here is a sample
       configuration:

          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  notifications  are set up the same way as Slack notifications, the webhook URL
       is different:

          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  notifications  are configured using “Discord Incoming Webhooks”. Here is a sample
       configuration:

          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 precedes
       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

       To configure IFTTT events, you need to retrieve your key from here:

       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:

       • value1: The type of change (new, changed, unchanged or error)

       • value2: The name of the job (name key in jobs.yaml)

       • value3: The location of the job (url, command or navigate key in jobs.yaml)

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

MATRIX

       You can have notifications sent to you through the Matrix protocol <https://matrix.org>.

       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/>:

       1. Open Riot.im <https://riot.im/app/> in a private browsing window

       2. Register/Log in as your bot, using its user ID and password.

       3. Set the display name and avatar, if desired.

       4. In  the  settings  page,  select  the "Help & About" tab, scroll down to the bottom and
          click Access Token: <click to reveal>.

       5. Copy the highlighted text to your configuration.

       6. Join the room that you wish to send notifications to.

       7. Go to the Room Settings (gear icon) and copy the Internal Room ID from the bottom.

       8. Close the private browsing window but do not log out, as this  invalidates  the  Access
          Token.

       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  need to configure your GMail account to allow for “less secure” (password-based) apps
       to login:

       1. Go to https://myaccount.google.com/

       2. Click on “Sign-in & security”

       3. Scroll all the way down to “Allow less secure apps” and enable it

       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)

       Same as the GMail configuration above, but use e.g.  email-smtp.us-west-2.amazonaws.com as
       the SMTP host, and username and port settings according to SES's login page.

SMTP LOGIN WITHOUT KEYRING

       If for whatever reason you cannot use a keyring to store your password (for example,  when
       using  it  from  a  cron  job)  you  can also set the insecure_password option in the SMTP
       config:

          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

       You can have notifications sent to you through the XMPP protocol.

       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

       You  can  have  notifications  sent to you through the Prowl push notification service, to
       receive the notification on iOS.

       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:

       1. Log into the Prowl website at https://prowlapp.com/

       2. Navigate to the “API Keys” tab.

       3. Scroll to the “Generate a new API key” section.

       4. Give the key a note that will remind you you've used it for urlwatch.

       5. Press “Generate Key”

       6. Copy the resulting key.

       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.

SHELL

       This  is  a  simple  reporter that pipes the text report notification to a command of your
       choice.     The     command     is     run     using      Python's      subprocess.Popen()
       <https://docs.python.org/3/library/subprocess.html#popen-constructor> with shell=False (to
       avoid possibly-unwanted shell expansion). Of course, you can create your own shell  script
       that does shell expansion and other things, and call that from the command.

       The  key  ignore_stdout  (defaults  to  true) can be used to ignore any output the program
       writes on stdout. The key ignore_stderr (defaults to false) can  be  used  to  ignore  any
       output the program writes on stderr.

       If  stdout/stderr  are not ignored, urlwatch will log any possible output in its --verbose
       log.

       The report written to stdin of the process is based on the output of  the  text  reporter,
       configuring the text reporter will adjust the data sent to the shell reporter.

       For example, to simply append reports to a file, configure it like this:

          shell:
            enabled: true
            command: ['tee', '-a', '/path/to/log.txt']
            ignore_stdout: true

FILES

       $XDG_CONFIG_HOME/urlwatch/urlwatch.yaml

SEE ALSO

       urlwatch(1), urlwatch-config(5), urlwatch-intro(7), urlwatch-cookbook(7)

COPYRIGHT

       2023 Thomas Perl

                                           May 03, 2023                     URLWATCH-REPORTERS(5)