Reporters

Reporters display or send the report containing the changes detected.

By default, the stdout reporter is enabled, and a text report is sent to the standard output (your terminal if you are running webchanges interactively).

Note

If running webchanges via cron or another scheduler service, the destination of the standard output depends on the scheduler and how it is configured.

The configuration file config.yaml contains the directives toggling the reporters available on or off, and their sub-directives (settings). This file is editable using any text editor or with the command webchanges --edit--config. Reporters are listed under the report section.

Each reporter has a directive called enabled that can be set to true or false.

Note

The config.yaml file is located in Linux or macOS in the ~/.config/webchanges directory, in Windows in the webchanges folder within your Documents folder (i.e. %USERPROFILE%\Documents\webchanges).

Note

The config.yaml file is created at the first run of webchanges --edit or webchanges --edit--config.

Tip: If you are running webchanges on a cloud server on a different timezone (e.g. UTC), see Time zone (global setting) below to set the time zone to be uses for reporting.

At the moment, the following reporters are available:

  • stdout (enabled by default): Display on stdout (the console).

  • Browser: Launch the default web browser.

  • Discord: Send to Discord channel.

  • Email: Send via email (SMTP or sendmail).

  • IFTTT: Send via IFTTT.

  • Mailgun: Send via email using the Mailgun service.

  • Matrix: Send to a room using the Matrix protocol.

  • Prowl: Send via prowlapp.com.

  • Pushbullet: Send via Pushbullet.

  • Pushover: Send via Pushover.

  • run_command: Run a custom command on the local system.

  • Telegram: Send via Telegram.

  • Webhook (Slack, Mattermost etc.): Send to an e.g. Slack or Mattermost channel using the service’s webhook.

  • XMPP: Send using the Extensible Messaging and Presence Protocol (XMPP).

Programmers can write their own reporter(s) as a hook. file.

Please note that many reporters need the installation of additional Python packages to work, as noted below and in dependencies.

Tip

While jobs are executed in parallel for speed, the output is sorted alphabetically in reports so you can use the name to control the order in which they appear in the report.

Changed in version 3.11: Reports are sorted by job name.

To test a reporter, use the --test-reporter command-line option with the name of the reporter, e.g. webchanges --test-reporter stdout. webchanges will generate dummy new, changed, unchanged and error notifications and send the ones configured to be sent under display via the selected reporter, in this example stdout. Any reporter that is configured and enabled can be tested.

For example, to test if your email reporter is configured correctly, use:

webchanges --test-reporter email

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

webchanges --test-reporter email --verbose

Reporters are based on reports, as follows, and inherit that report’s settings:

html
└───browser
text
├───stdout
├───email
├───ifttt
├───webservice (no settings)
│   ├───pushover
│   └───pushbullet
├───mailgun
├───discord
├───webhook
│   ├───slack
│   └───shell
├───xmpp
├───prowl
└───run_command
markdown
├───telegram
└───matrix

Note

Even though the email reporter is listed under text for historical reason, it also inherits from the html report when its html option is set to true (default).

Time zone (global setting)

You can set the timezone for reports by entering a IANA time zone name in the tz directive of the report section. This is useful if for example you are running webchanges on a cloud server on a different timezone (e.g. UTC). Note that this directive is ignored by any outside differs called by the :ref:command_diff differ.

report:
  tz: America/New York

If the directive is missing, or its value is null or blank, the timezone of the system that webchanges runs on will be used in reports.

New in version 3.8.

Browser

Displays the HTML report using the system’s default web browser.

report:
  tz: null  # or whatever you want it to be
  browser:
    enabled: true  # don't forget to set this to true! :)

New in version 3.0.

Discord

Sends a text report as a message in a Discord channel.

To use this reporter you must first create a webhook in Discord. From your Discord server settings select Integration and create a “New Webhook”, give the webhook a name to post under, select a channel, press on “Copy Webhook URL” and paste the URL into the configuration as seen below (see here for Discord’s help).

report:
  tz: null  # or whatever you want it to be
  webhook:
    enabled: true  # don't forget to set this to true! :)
    webhook_url: https://discordapp.com/api/webhooks/11111XXXXXXXXXXX/BBBBYYYYYYYYYYYYYYYYYYYYYYYyyyYYYYYYYYYYYYYY
    embed: true
    subject: "[webchanges] {count} changes{jobs_files}: {jobs}"
    colored: true

Embedded content might make it easier to read and identify individual reports. If embed is set to true then the subject will be the content of the message and the report will be shown as embedded text; if colored is also set to true then the report will be embedded as code of diff type, enabling Discord’s syntax highlighting and colorization.

Sub-directives

  • webhook_url (required): The Discord webhook URL.

  • embed: If true, the content will be sent as an Embed object (true/false). Default is true.

  • subject: Only relevant if embed is true, it’s a string that precedes the embedded report; use {count} for the number of reports, {jobs} for the title of jobs reported, and {jobs_files} for a space followed by the name of the jobs file(s) used within parenthesis, stripped of preceding jobs-, if not using the default jobs.yaml. Default: [webchanges] {count}  changes:{jobs_files} {jobs}.

  • colored: If true, the report will an Embed object formatted as diff code to enable colored syntax highlighting (true/false). Default is true.

  • max_message_length: The maximum length of a message in characters. Default is the maximum allowed by Discord: either 2,000 or, if embed is true, 4,096.

Changed in version 3.9.2: Added sub-directives embed, subject and colored.

Email

Sends the report via email (via SMTP or the sendmail external program).

Sub-directives

  • method: Either smtp or sendmail.

  • from: The sender’s email address. Do not use your main email address but create a throwaway one!

  • to: The destination email address(es); if sending to more than one recipient, concatenate the addresses with a comma (,).

  • subject: The subject line. Use {count} for the number of reports, {jobs} for the title of jobs reported, and {jobs_files} for a space followed by the name of the jobs file(s) used within parenthesis, stripped of preceding jobs-, if not using the default jobs.yaml. Default: [webchanges] {count} changes:{jobs_files} {jobs}.

  • html: Whether the email includes HTML (true/false).

SMTP

Plaintext password

You can save a password in the insecure_password directive in the SMTP configuration section to enable unattended scheduled runs of webchanges. As the name says, storing the password as plaintext in the configuration is insecure and bad practice, yet for a throwaway account that is only used for sending these reports this might be a low-risk way to run unattended.

report:
  tz: null  # or whatever you want it to be
  email:
    enabled: true  # don't forget to set this to true! :)
    from: webchanges <throwawayaccount@example.com>  # (edit accordingly; don't use your primary account for this!!)
    to: myself@example.com, someonelse@example.com  # The email address(es) of where want to receive reports
    subject: "[webchanges] {count} changes: {jobs}"
    html: true
    method: smtp
    smtp:
      host: smtp.example.com
      port: 587
      user: throwawayaccount@example.com  # (edit accordingly; don't use your primary account for this!!)
      starttls: true
      auth: true
      insecure_password: "this_is_my_secret_password"

Warning

Never ever use this method with your your primary email account! Seriously! This method makes it really easy for your password to be picked up by software (e.g. a virus) running on your machine, by other users logged into the system, and/or for the password to appear in log files accidentally, so it’s insecure. Create a throw-away free email account just for sending out these emails.

Keyring password

A secure way to store your password is to use a keyring by running webchanges --smtp-login after configuring your host and user; this requires installing the optional safe_password dependencies (see optional packages below). Be aware that the use of keyring won’t allow you to run webchanges unattended (e.g. from a scheduler). If you’re storing the password in a keyring, the insecure_password key is ignored and can be left blank.

SMTP sub-directives

  • host: The address of the SMTP server. Default is ‘localhost’

  • port: The port used to communicate with the server. Default is 25.

  • starttls: Whether the server uses SSL/TLS encryption (true/false). Default is true.

  • user: The username used to authenticate.

  • auth: Whether authentication via username/password is required (true/false). Default is true.

  • insecure_password: The password used to authenticate (if keyring is not used).

Amazon Simple Email Service (SES) example

First ensure that you have configured SES as per the Quick start

Create an email address just for sending mails from webchanges and similar programs for security reasons (so you can easily recover from a compromised user/password leak from, e.g. from a scan of your jobs file), then configure these directives as follows:

report:
  tz: America/New_York  # or whatever you want it to be
  email:
    enabled: true  # don't forget to set this to true! :)
    from: my_programs@verified_domain.com  # (edit accordingly)
    to: your.destination@example.org  # The email address you want to send reports to
    subject: "{count} changes: {jobs}"
    html: true
    method: smtp
    smtp:
      host: email-smtp.us-west-2.amazonaws.com  # (edit accordingly)
      user: ABCDEFGHIJ1234567890  # (edit accordingly)
      port: 587  # (25 or 465 also work)
      starttls: true
      auth: true
      insecure_password: "this_is_my_secret_password"  # (edit accordingly)

Gmail example

Important

The functionality described below is available only on Google Workspace and Google Cloud Identity accounts, but not on regular @gmail.com accounts, because as of “May 30, 2022 Google no longer supports the use of third-party apps or devices which ask you to sign in to your Google Account using only your username and password”. You can still use a @gmail account address to send emails using the Amazon Simple Email Service (see above).

Warning

You do not want to do this with your primary Google account, but rather set up a separate one just for sending mails from webchanges and similar programs. Allowing less secure apps and storing the password (even if it’s in the Keychain) is not good security practice for your primary account. You have been warned!

First configure your Google Workspace or Google Cloud Identity account to allow for “less secure” (password-based) apps to login:

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

  2. Turn Allow less secure apps access ON

For more information, see Google’s help. This setting may not be available if the account administrator turned the functionality off and you therefore cannot use this functionality.

Then configure these directives as follows:

report:
  tz: null  # or whatever you want it to be
  email:
    enabled: true  # don't forget to set this to true! :)
    from: my_programs@googleworkspacedomain.com  # (edit accordingly; don't use your primary account for this!!)
    to: your.destination@example.org  # The email address of where want to receive reports
    subject: "[webchanges] {count} changes: {jobs}"
    html: true
    method: smtp
    smtp:
      host: smtp.gmail.com
      user: my_programs@googleworkspacedomain.com  # (edit accordingly; don't use your primary account for this!!)
      port: 587
      starttls: true
      auth: true
      insecure_password: "this_is_my_secret_password"  # (edit accordingly)

sendmail

Calls the external sendmail program (linux only), which must already be installed and configured.

Optional packages

If using a Keychain to store the password, you also need to:

  • Install the safe_password optional package as per below;

  • Install all the dependencies of the keyring package as per documentation here;

  • Configure the keyring package to use the Keychain backend being used in your system following the instructions on the same page.

pip install --upgrade webchanges[safe_password]

Changed in version 3.10: Can specify multiple “to” email addresses.

IFTTT

Sends a text report as an IFTTT event.

To configure IFTTT events, you need to retrieve your key from https://ifttt.com/maker_webhooks/settings.

The URL is shown in “Account Info” and 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):

report:
  tz: null  # or whatever you want it to be
  ifttt:
    enabled: true  # don't forget to set this to 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 directive in jobs.yaml)

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

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

Mailgun

Sends a text report via email using the commercial Mailgun service.

Sub-directives

  • domain: The domain.

  • api_key: API key (see here).

  • from_name: Sender’s name.

  • from_mail: Sender’s email address.

  • to: Recipient’s email address.

  • subject: The subject line. Use {count} for the number of reports, {jobs} for the title of jobs reported, and {jobs_files} for a space followed by the name of the jobs file(s) used within parenthesis, stripped of preceding jobs-, if not using the default jobs.yaml. Default: [webchanges] {count} changes:{jobs_files} {jobs}.

  • region (optional): The code of the region if different from the US (e.g. eu).

Matrix

Sends a text or Markdown report as a notification through the Matrix protocol.

You first need to register a Matrix account for the bot on any home server.

You then need to acquire an access token and room ID, using the following instructions adapted from this guide:

  1. Open Riot.im 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:

report:
  tz: null  # or whatever you want it to be
  matrix:
    enabled: true  # don't forget to set this to true! :)
    homeserver: https://matrix.org
    access_token: "YOUR_TOKEN_HERE"
    room_id: "!roomroomroom:matrix.org"

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

report:
  tz: null  # or whatever you want it to be
  markdown:
    enabled: true  # don't forget to set this to true! :)
    markdown: false
    details: false
    footer: false
    minimal: true

Prowl

Sends a text report through the Prowl push notification service (iOS only).

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:

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

  2. If needed, 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 this service.

  5. Press “Generate Key”.

  6. Copy the resulting key.

Here is a sample configuration:

report:
  tz: null  # or whatever you want it to be
  prowl:
    enabled: true  # don't forget to set this to true! :)
    api_key: "<your api key here>"
    priority: 2
    application: webchanges example
    subject: "{count} changes: {jobs}"

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

Sub-directives

  • api_key: The API key.

  • application: The application.

  • priority: The priority (integer). Default: 0

  • subject: The subject line. Use {count} for the number of reports, {jobs} for the title of jobs reported, and {jobs_files} for a space followed by the name of the jobs file(s) used within parenthesis, stripped of preceding jobs-, if not using the default jobs.yaml. Default: [webchanges] {count} changes:{jobs_files} {jobs}.

New in version 3.0.1.

Pushbullet

Sends a text report through the Pushbullet notification service.

Pushbullet notifications are configured similarly to Pushover. You will need to add to the configuration your Pushbullet Access Token, which you can generate at https://www.pushbullet.com/#settings.

Required packages

To use this report you need to install optional packages. Install them using:

pip install --upgrade webchanges[pushbullet]

Sub-directives

  • api_key: The API key.

Pushover

Sends a text report through the Pushover notification service.

You can configure webchanges to send real time notifications about changes via Pushover. Firsly, make sure you have the required packages installed (see below). Then edit your configuration file (webchanges --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 webchanges as an application on your Pushover account.

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 (webchanges --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.

Required packages

To use this report you need to install optional packages. Install them using:

pip install --upgrade webchanges[pushover]

Sub-directives

  • app: The application.

  • user: The user.

  • device: The device. Default: Null.

  • sound: The sound (string). Default: spacealarm.

  • priority: The priority (string). Default: normal.

run_command

Runs a command on your local system supplying a text report.

Any text in the command that matches the keywords below will be substituted as follows:

Text in command

Replacement

{count}

The number of reports

{jobs}

The titles of the jobs reported

{text}

The report in text format

For example, in Windows we can make a MessageBox pop up:

report:
  tz: null  # or whatever you want it to be
  run_command:
    enabled: true  # don't forget to set this to true! :)
    command: start /MIN PowerShell -Command "Add-Type -AssemblyName PresentationFramework;[System.Windows.MessageBox]::Show('{count} changes: {jobs}\n{text}')"

All environment variables are preserved and the following ones added:

Environment variable

Description

WEBCHANGES_REPORT_CONFIG_JSON

All report parameters in JSON format

WEBCHANGES_CHANGED_JOBS_JSON

All parameters of changed jobs in JSON format

If the command generates an error, the output of the error will be reported in the first line(s).

New in version 3.8.

Changed in version 3.9: Added environment variable WEBCHANGES_CHANGED_JOBS_JSON

stdout

Displays a text report on stdout (the console).

Optional sub-directives

  • color: Uses color (green for additions, red for deletions) (true/false).

Telegram

Sends a Markdown report to Telegram using its Bot API.

Groups

A Telegram group is the standard method used to receive notifications from webchanges. To create one, 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’s unique authentication token (along the lines of 110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw); add it to your configuration file (run webchanges --edit-config) as below, and save the file.

report:
  tz: null  # or whatever you want it to be
  telegram:
    enabled: true  # don't forget to set this to true! :)
    bot_token: "110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"  # replace with your bot's token
    chat_id: ""  # empty for now

Next click on the link of your chat bot (starts with https://t.me/) and, on the new screen, click on start (which will send the message /start) and enter any text (“Hello” is fine). Then run webchanges --telegram-chats, which will list the group(s) the bot is involved with as well as their unique identifier(s). Enter the identifier(s) of the group(s) you want to be notified into the configuration file (run webchanges --edit-config) as chat_id:

report:
  tz: null  # or whatever you want it to be
  telegram:
    enabled: true  # don't forget to set this to true! :)
    bot_token: "110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"  # replace with your bot's token
    chat_id: 88888888  # the chat id where the messages should be sent
    silent: false  # set to true to receive a notification without any sound

You may add multiple chat IDs as a YAML list:

report:
  tz: null  # or whatever you want it to be
  telegram:
    enabled: true  # don't forget to set this to true! :)
    bot_token: "110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"  # replace with your bot's token
    chat_id:
      - 11111111  # positive chat IDs are private groups
      - -22222222  # negative chat IDs are public groups
    silent: true  # set to false to receive a notification with sound

Note

Before adding a group to webchanges, make sure that it has at least one message in it.

Hint

Public groups have chat IDs starting with a - (negative) sign; make sure you don’t leave this out by mistake!

Channels

To notify a Telegram channel of which the bot is admin of, enter the the username of the channel (the text after https://t.me/s/, prefixed by an @) as a chat_id, like this:

report:
  tz: null  # or whatever you want it to be
  telegram:
    enabled: true  # don't forget to set this to true! :)
    bot_token: "110201543:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw"  # replace with your bot's token
    chat_id:
      - "@channelusername"  # replace with your channel's username

Optional sub-directives

  • silent: Receive a notification without any sound (true/false). Default is false.

Changed in version 3.7: Switched from the text to the markdown report type.

New in version 3.7: silent sub-directive.

Webhook (Slack, Mattermost etc.)

Sends a text or Markdown report to services such as Slack, Mattermost etc. using a webhook.

report:
  tz: null  # or whatever you want it to be
  webhook:
    enabled: true  # don't forget to set this to true! :)
    webhook_url: https://hooks.slack.com/services/T50TXXXXXU/BDVYYYYYYY/PWTqwyFM7CcCfGnNzdyDYZ

webhook uses the text report type unless the sub-directive markdown: true is present, in which case it uses the Markdown report.

Slack

To set up Slack, create a new Slack app in the workspace where you want to post messages, toggle Activate Incoming Webhooks on in the Features page, click Add New Webhook to Workspace, pick a channel that the app will post to, then click Authorize (see here). Copy the webhook URL and paste it into the configuration as seen above.

Mattermost

To set up Mattermost follow the documentation here to generate a webhook URL and paste it into the configuration as such (note that Mattermost prefers markdown so we’re setting markdown: true):

report:
  tz: null  # or whatever you want it to be
  webhook:
    enabled: true  # don't forget to set this to true! :)
    webhook_url: http://{your-mattermost-site}/hooks/xxx-generatedkey-xxx
    markdown: true  # Mattermost prefers markdown

Sub-directives

  • webhook_url (required): The webhook URL.

  • markdown: Whether to send Markdown instead of plain text (true/false). Default is false.

  • max_message_length: The maximum length of a message in characters. Default is 40,000.

  • rich_text: Whether to send preformatted rich text (for Slack) (true/false). Default is false.

Changed in version 3.0.1: Renamed from slack to webhook and added the markdown sub-directive.

XMPP

Sends a text report using the XMPP protocol.

This reporter should be only used with an XMPP account that is exclusively used for webchanges; create a new one for this purpose.

Here is a sample configuration:

report:
  tz: null  # or whatever you want it to be
  xmpp:
    enabled: true  # don't forget to set this to true! :)
    sender: "BOT_ACCOUNT_NAME"
    recipient: "YOUR_ACCOUNT_NAME"

You can store your password securely on a Keychain if you have one installed by running webchanges --xmpp-login; this also requires having the optional safe_password dependencies installed (see below). However, be aware that the use of safe password and keyring won’t allow you to run webchanges unattended (e.g. from a scheduler), so you can save the password in the insecure_password directive in the XMPP config instead:

report:
  tz: null  # or whatever you want it to be
  xmpp:
    enabled: true  # don't forget to set this to true! :)
    sender: "BOT_ACCOUNT_NAME"
    recipient: "YOUR_ACCOUNT_NAME"
    insecure_password: "this_is_my_secret_password"

As the name says, storing the password as plaintext in the configuration is insecure and bad practice, yet for an account that only sends these reports this might be a low-risk way.

Required packages

To run jobs with this reporter, you need to install optional packages. Install them using:

pip install --upgrade webchanges[xmpp]

Optional packages

If using a Keychain to store the password, you also need to:

  • install the safe_password optional package as per below,

  • install all the dependencies of the keyring package as per documentation here,

  • configure the keyring package to use the keychain backend you’re using in your system following the instructions on the same page.

pip install --upgrade webchanges[safe_password]