Jobs

Jobs are the kind of things that urlwatch can monitor.

The list of jobs to run are contained in the configuration file urls.yaml, accessed with the command urlwatch --edit, each separated by a line containing only ---.

While optional, it is recommended that each job starts with a name entry:

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

URL

This is the main job type – it retrieves a document from a web server:

name: "urlwatch homepage"
url: "https://thp.io/2008/urlwatch/"

Required keys:

  • url: The URL to the document to watch for changes

Job-specific optional keys:

  • cookies: Cookies to send with the request (see Advanced Topics)

  • method: HTTP method to use (default: GET)

  • data: HTTP POST/PUT data

  • ssl_no_verify: Do not verify SSL certificates (true/false)

  • ignore_cached: Do not use cache control (ETag/Last-Modified) values (true/false)

  • http_proxy: Proxy server to use for HTTP requests

  • https_proxy: Proxy server to use for HTTPS requests

  • headers: HTTP header to send along with the request

  • encoding: Override the character encoding from the server (see Advanced Topics)

  • timeout: Override the default socket timeout (see Advanced Topics)

  • ignore_connection_errors: Ignore (temporary) connection errors (see Advanced Topics)

  • ignore_http_error_codes: List of HTTP errors to ignore (see Advanced Topics)

  • ignore_timeout_errors: Do not report errors when the timeout is hit

  • ignore_too_many_redirects: Ignore redirect loops (see Advanced Topics)

(Note: url implies kind: url)

Command

This job type allows you to watch the output of arbitrary shell commands, which is useful for e.g. monitoring a FTP uploader folder, output of scripts that query external devices (RPi GPIO), etc…

name: "What is in my Home Directory?"
command: "ls -al ~"

Required keys:

  • command: The shell command to execute

Job-specific optional keys:

  • none

(Note: command implies kind: shell)

Optional keys for all job types

  • name: Human-readable name/label of the job

  • filter: filters (if any) to apply to the output

  • max_tries: Number of times to retry fetching the resource

  • diff_tool: Command to a custom tool for generating diff text

  • compared_versions: Number of versions to compare for similarity

  • kind (redundant): Either url, shell or browser. Automatically derived from the unique key (url, command or navigate) of the job type