urlwatch Documentation

Jobs are the units of monitoring in urlwatch. They are defined in the urls.yaml configuration file.

• Use urlwatch --edit to open the configuration file for editing.
• Use urlwatch --list to see a list of all jobs and their automatically assigned index numbers.

It is recommended to provide a name for each job for better readability:

name: "This is a human-readable name/label of the job"

You can send notifications via the XMPP protocol. It is recommended to register a dedicated XMPP account for urlwatch.

Configure the reporter as follows:

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

To securely store your XMPP password in the keychain, run:

urlwatch --xmpp-login

Additional features in urlwatch (like specific reporters, filters, or job kinds) require optional Python packages. Install the required package(s) using pip based on the feature you want to use.

python3 -m pip install <packagename>

urlwatch uses the url (for URL/Browser jobs) or navigate (for Browser jobs) and command (for Shell jobs) keys as unique identifiers. To monitor the same URL multiple times, you must make the identifier unique by appending a fragment (e.g., #1, #2) to the URL.

name: "Looking for Thing A"
url: http://example.com/#1
filter:
  - grep: "Thing A"
---
name: "Looking for Thing B"
url: http://example.com/#2
filter:
  - grep: "Thing B"

You can install urlwatch for the first time or upgrade an existing installation using pip. It is recommended to use python -m pip to ensure you are targeting the correct Python environment.

python -m pip install --upgrade urlwatch

To use Amazon Simple Email Service (SES), use the SMTP configuration method. Replace the GMail host with your SES SMTP endpoint (e.g., email-smtp.us-west-2.amazonaws.com) and use the credentials and port provided by your SES settings.

report:
  email:
    enabled: true
    from: your-verified-ses-email@example.com
    to: destination@example.com
    method: smtp
    smtp:
      host: email-smtp.us-west-2.amazonaws.com
      auth: true
      port: 465
      # Use settings from your SES login page

To simulate an HTML form submission, provide the form fields in the data field of the job description. By default, urlwatch uses the HTTP POST method and sets the Content-type to application/x-www-form-urlencoded.

name: "My POST Job"
url: http://example.com/foo
data:
  username: "foo"
  password: "bar"
  submit: "Send query"

You can verify if a reporter is correctly configured by using the --test-reporter command-line option followed by the reporter name. This generates a test report containing new, changed, unchanged, and error notifications.

To test the stdout reporter:

urlwatch --test-reporter stdout

To test an email reporter:

urlwatch --test-reporter email

If notifications fail, use the --verbose flag to view detailed debug logs.

You can customize the HTTP method and Content-type header to send arbitrary requests (like PUT) by using the method and headers keys.

name: "My PUT Request"
url: http://example.com/item/new
method: PUT
headers:
  Content-type: application/json
data: '{"foo": true}'