Configuration¶

Deprecation Notice¶

Watchtower v2 Legacy Notification Deprecation

Watchtower has a number of legacy notification options that will be removed with the release of Watchtower v2:

Email Notifications
Slack Notifications
Microsoft Teams Notifications
Gotify Notifications

Migration to the NOTIFICATION URL with the appropriate Shoutrrr URL scheme is strongly recommended.

Use watchtower notify-upgrade to help convert legacy email configurations to Shoutrrr URLs or use the Shoutrrr Playground to help convert configurations for other services to Shoutrrr URLs.

Overview¶

Watchtower uses Shoutrrr to provide notification functionality. Notifications are sent via hooks in the logrus logging system.

Enabling Notifications¶

To send notifications, use the NOTIFICATION URL configuration option to specify the Shoutrrr service URL.

The Shoutrrr URL follows the format:

<service>://<required-credentials>[:<optional-credentials>]@<required-service>/<required-path>?<key>=<value>&...

The format is the same for all services, but the parameters, path, and credentials vary between them.

The NOTIFICATION URL configuration option can also reference a file, in which case the contents of the file are used.

Using Multiple Notification Services¶

Watchtower supports sending notifications to multiple services simultaneously. The preferred method is to use multiple Shoutrrr URL's.

For most Watchtower deployments via Docker Compose, this is best achieved via using either a comma-separated list or YAML array for the WATCHTOWER_NOTIFICATION_URL environment variable. When running Watchtower via the Docker CLI, the --notification-url CLI flag can be used multiple times, or use a comma-separated list.

Environment Variable Format

WATCHTOWER_NOTIFICATION_URL supports comma-separated and space-separated values.
Commas within URLs (e.g., in query parameters) are preserved.
For Docker Compose, the YAML array syntax is the recommended approach.

Docker CLIDocker Compose

Environment VariableFlags

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATION_URL="discord://token@webhookid,telegram://token@telegram?chats=@channel" \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notification-url "discord://token@webhookid" \
--notification-url "telegram://token@telegram?chats=@channel"

YAML ArraySingle-lineMulti-line

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATION_URL:
        - "discord://token@webhookid"
        - "telegram://token@telegram?chats=@channel"
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: "discord://token@webhookid,telegram://token@telegram?chats=@channel"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATION_URL: >
        discord://token@webhookid,
        telegram://token@telegram?chats=@channel
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Do NOT define the variable multiple times

Defining WATCHTOWER_NOTIFICATION_URL multiple times in your environment will cause the last value to overwrite previous ones:

# WRONG - Only the second URL will be used:
environment:
- WATCHTOWER_NOTIFICATION_URL=discord://xxx
- WATCHTOWER_NOTIFICATION_URL=telegram://xxx

CLI Flags vs Environment Variables

The CLI flag can be called multiple times as CLI arguments; however, defining the environment variable multiple times will NOT work and only the last value will be used.

This is because CLI flags use a StringArray type that supports multiple invocations, while environment variables are simple key-value pairs that get overwritten when defined multiple times.

For environment variables, use comma-separated values or YAML arrays instead.

Verifying Multiple Notifications¶

When Watchtower starts, check the logs for the notification summary:

time="2026-01-28T16:07:24+01:00" level=info msg="Using notifications: discord, telegram"

If you only see one service listed (e.g., Using notifications: telegram), your multiple URL configuration was not parsed correctly.

Startup Notifications¶

Watchtower will log and send a notification every time it is started.

This behavior can be disabled with the DISABLE STARTUP MESSAGE configuration option.

General Notification Settings¶

Level¶

Controls the log level for notifications.

Possible values: panic, fatal, error, warn, info, debug, trace.

            Argument: --notifications-level
Environment Variable: WATCHTOWER_NOTIFICATIONS_LEVEL
                Type: String
             Default: info

Note

The notification level setting applies to both report mode (--notification-report=true) and legacy (log-only) mode (--notification-report=false). Legacy mode is deprecated; use report mode with --notification-url for new configurations.

Hostname¶

Custom hostname specified in subject/title. Useful for overriding the operating system hostname.

            Argument: --notifications-hostname
Environment Variable: WATCHTOWER_NOTIFICATIONS_HOSTNAME
                Type: String
             Default: None

Delay¶

Delay before sending notifications expressed in seconds.

            Argument: --notifications-delay
Environment Variable: WATCHTOWER_NOTIFICATIONS_DELAY
                Type: Integer
             Default: None

Title Tag¶

Prefix to include in the title. Useful when running multiple Watchtower instances.

            Argument: --notification-title-tag
Environment Variable: WATCHTOWER_NOTIFICATION_TITLE_TAG
                Type: String
             Default: None

Skip Title¶

Used to not pass the title param to notifications. This will not pass a dynamic title override to notification services. If no title is configured for the service, it will remove the title altogether.

            Argument: --notification-skip-title
Environment Variable: WATCHTOWER_NOTIFICATION_SKIP_TITLE
                Type: Boolean
             Default: false

Log Stdout¶

Enable output from logger:// Shoutrrr service to stdout.

            Argument: --notification-log-stdout
Environment Variable: WATCHTOWER_NOTIFICATION_LOG_STDOUT
                Type: Boolean
             Default: false

Split by Container¶

Send separate notifications for each updated container instead of grouping them.

            Argument: --notification-split-by-container
Environment Variable: WATCHTOWER_NOTIFICATION_SPLIT_BY_CONTAINER
                Type: Boolean
             Default: false

Note

When disabled (default), notifications are grouped for all updated containers in a single session. When enabled, a separate notification is sent for each container update.

Usage Example¶

To enable separate notifications per container:

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_URL="slack://hook:xxxx-yyyy-zzzz@webhook?botname=watchtower" \
  -e WATCHTOWER_NOTIFICATION_SPLIT_BY_CONTAINER=true \
  nickfedor/watchtower

Notification Templates¶

Watchtower allows you to customize the format and content of notification messages using Go templates. You can define templates either inline or load them from a file.

Inline Templates¶

Use the --notification-template argument or WATCHTOWER_NOTIFICATION_TEMPLATE environment variable to specify a template directly as a string.

File-Based Templates¶

For more complex templates or better maintainability, use the --notification-template-file argument or WATCHTOWER_NOTIFICATION_TEMPLATE_FILE environment variable to specify a path to a template file.

Note

When both inline and file-based templates are specified, the file-based template takes precedence.

For detailed information about template syntax, available data structures, and examples, see the Notification Templates documentation.

Email Notifications¶

Watchtower uses Shoutrrr's smtp service to send email notifications.

Deprecated

Legacy email notification flags (e.g., --notification-email-from, --notification-email-to, --notification-email-server) are deprecated. Use --notification-url with an smtp:// URL instead. See Transitioning from Legacy Email Notifications to Shoutrrr below.

To send notifications via e-mail, use an smtp:// URL with --notification-url:

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATION_URL="smtp://user:[email protected]:587/[email protected]&[email protected]" \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notification-url "smtp://user:[email protected]:587/[email protected]&[email protected]"

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATION_URL: smtp://user:[email protected]:587/[email protected]&[email protected]
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Common SMTP Configurations¶

GmailAWS SESMicrosoft 365Generic (SSL)Generic (Plain)

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://${USER}:${PASSWORD}@smtp.gmail.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Note

For Gmail, use an App Password if two-factor authentication is enabled.

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://${USER}:${PASSWORD}@email-smtp.us-east-1.amazonaws.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Property	Value
Port	`587`
Encryption	`ExplicitTLS`
UseStartTLS	`Yes`

smtp://${USER}:${PASSWORD}@smtp.office365.com:587/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ExplicitTLS&usestarttls=yes&timeout=30s

Property	Value
Port	`465`
Encryption	`ImplicitTLS`
UseStartTLS	`No`

smtp://${USER}:${PASSWORD}@smtp.example.com:465/?fromaddress=${FROM}&toaddresses=${TO}&encryption=ImplicitTLS&usestarttls=no&timeout=30s

Property	Value
Port	`25`
Encryption	`None`
UseStartTLS	`No`

smtp://${USER}:${PASSWORD}@smtp.example.com:25/?fromaddress=${FROM}&toaddresses=${TO}&encryption=None&usestarttls=no&timeout=30s

Notes¶

Timeout:
- The default SMTP timeout is 10 seconds.
- If you experience timeouts (e.g., failed to send: timed out: using smtp), add &timeout=30s to the URL to allow more time for server responses, especially with proxies or slow networks.
Authentication:
- Use &auth=Plain for username/password authentication (default if credentials provided).
- For OAuth2 (e.g., Gmail with app-specific passwords), use &auth=OAuth2.
Testing:
- Install Shoutrrr using one of the various installation methods.
- Test your URL with the Shoutrrr CLI:
```
shoutrrr send -u <URL> -m "Test message"
```
Proxy Issues:
- If using a Docker proxy (e.g., tcp://dockerproxy:2375), ensure it allows outbound connections to ${SMTP_HOST}:${SMTP_PORT}.
- Test connectivity with telnet ${SMTP_HOST} ${SMTP_PORT} inside the container.

The following legacy smtp configuration options and examples are deprecated and will be removed with the release of Watchtower v2.

Deprecated SMTP Configuration Options¶

Email From¶

The e-mail address from which notifications will be sent.

            Argument: --notification-email-from
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_FROM
                Type: String
             Default: None

Email To¶

The e-mail address to which notifications will be sent.

            Argument: --notification-email-to
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_TO
                Type: String
             Default: None

Email Server¶

The SMTP server (IP or FQDN) to send notifications through.

            Argument: --notification-email-server
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER
                Type: String
             Default: None

Email Server TLS Skip Verify¶

Skip verification of the server certificate when using TLS.

            Argument: --notification-email-server-tls-skip-verify
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER_TLS_SKIP_VERIFY
                Type: Boolean
             Default: false

Email Server User¶

The username for the SMTP server if it requires authentication.

            Argument: --notification-email-server-user
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER
                Type: String
             Default: None

Email Server Password¶

The password for the SMTP server if it requires authentication.

            Argument: --notification-email-server-password
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD
                Type: String
             Default: None

Note

This option can also reference a file, in which case the contents of the file are used.

Email Subject Tag¶

Subject prefix tag for notifications via mail.

            Argument: --notification-email-subjecttag
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SUBJECTTAG
                Type: String
             Default: ""

Email Server Port¶

The port the SMTP server listens on.

            Argument: --notification-email-server-port
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT
                Type: Integer
             Default: 25

Email Delay¶

The delay (in seconds) between sending notifications if multiple containers are updated at once.

            Argument: --notification-email-delay
Environment Variable: WATCHTOWER_NOTIFICATION_EMAIL_DELAY
                Type: Integer
             Default: None

Deprecated SMTP Configuration Examples¶

Docker CLIDocker Compose

Env VarsFlagsEnv Vars (SMTP Relay)Flags (SMTP Relay)

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=user \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=secret \
-e WATCHTOWER_NOTIFICATION_EMAIL_DELAY=10 \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notifications email \
--notification-email-from [email protected] \
--notification-email-to [email protected] \
--notification-email-server smtp.example.com \
--notification-email-server-port 587 \
--notification-email-server-user user \
--notification-email-server-password secret \
--notification-email-delay 10

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
-e WATCHTOWER_NOTIFICATIONS=email \
-e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
-e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=relay.example.com \
nickfedor/watchtower

docker run -d \
--name watchtower \
-v /var/run/docker.sock:/var/run/docker.sock \
nickfedor/watchtower \
--notifications email \
--notification-email-from [email protected] \
--notification-email-to [email protected] \
--notification-email-server relay.example.com

Note

This assumes that you already have an SMTP server up and running that you can connect to. If you don't or you want to bring up Watchtower with your own simple SMTP relay, then check out the Docker Compose example.

Docker ComposeSMTP Relay

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATIONS: email
    WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.example.com
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: user
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: secret
    WATCHTOWER_NOTIFICATION_EMAIL_DELAY: 10
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

services:
watchtower:
    image: nickfedor/watchtower:latest
    environment:
    WATCHTOWER_NOTIFICATIONS: email
    WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
    WATCHTOWER_NOTIFICATION_EMAIL_SERVER: relay.example.com
    volumes:
    - /var/run/docker.sock:/var/run/docker.sock

Note

The example assumes that your domain is called example.com and that you are going to use a valid certificate for smtp.example.com.

This hostname has to be used as WATCHTOWER_NOTIFICATION_EMAIL_SERVER, otherwise the TLS connection will fail with Failed to send notification email or connection: connection refused errors.

We also have to add a network for this setup in order to add an alias to it.

If you also want to enable DKIM or other features on the SMTP server, then you will find more information at freinet/postfix-relay

Migrating Deprecated SMTP Notifications to Shoutrrr URLs¶

Important

Legacy email notification flags are deprecated. Follow the steps below to migrate to --notification-url with an smtp:// URL.

Watchtower includes a watchtower notify-upgrade command to automatically convert legacy flags to a Shoutrrr URL.

The output is written to a temporary file, which you can copy using:

docker cp <CONTAINER>:<FILE_PATH> ./watchtower-notifications.env

Example Walkthrough¶

Example Legacy Configuration:

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=email \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587 \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=[email protected] \
  -e WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=secret \
  -e WATCHTOWER_NOTIFICATION_EMAIL_FROM=[email protected] \
  -e WATCHTOWER_NOTIFICATION_EMAIL_TO=[email protected] \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notifications email \
  --notification-email-server smtp.example.com \
  --notification-email-server-port 587 \
  --notification-email-server-user [email protected] \
  --notification-email-server-password secret \
  --notification-email-from [email protected] \
  --notification-email-to [email protected]

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATIONS: email
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER: smtp.example.com
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT: 587
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER: [email protected]
      WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD: secret
      WATCHTOWER_NOTIFICATION_EMAIL_FROM: [email protected]
      WATCHTOWER_NOTIFICATION_EMAIL_TO: [email protected]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Run the following CLI command:

docker compose exec watchtower watchtower notify-upgrade

Converted Shoutrrr URL:

smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes

Replace the deprecated configuration with:

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_URL=smtp://[email protected]:[email protected]:587/?fromaddress=[email protected]&toaddresses=[email protected]&encryption=ExplicitTLS&usestarttls=yes \
  -e WATCHTOWER_NOTIFICATIONS_DELAY=10 \
  -e WATCHTOWER_NOTIFICATION_TITLE_TAG=Watchtower \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes" \
  --notifications-delay 10 \
  --notification-title-tag Watchtower

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: smtp://[email protected]:[email protected]:587/[email protected]&[email protected]&encryption=ExplicitTLS&usestarttls=yes
      WATCHTOWER_NOTIFICATIONS_DELAY: "10"
      WATCHTOWER_NOTIFICATION_TITLE_TAG: Watchtower
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Note

Avoid using unrecognized flags like WATCHTOWER_NOTIFICATION_EMAIL_SERVER_SSL, as they are ignored and may cause confusion.

Use the encryption and usestarttls URL parameters in the smtp:// URL to control TLS behavior rather than deprecated flags.

Slack Notifications¶

Deprecated

Legacy Slack flags (--notification-slack-hook-url, --notification-slack-identifier, etc.) are deprecated. Use --notification-url with a slack:// URL instead.

Example Slack Configuration¶

To receive notifications in Slack, use a slack:// or discord:// URL with --notification-url:

Docker CLIDocker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "slack://hook:AAAA-BBBB-CCCC@webhook?botname=watchtower"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: "slack://hook:AAAA-BBBB-CCCC@webhook?botname=watchtower"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

The following legacy Slack configuration options and examples are deprecated and will be removed with the release of Watchtower v2.

Slack Legacy Configuration Options¶

The following legacy Slack flags are deprecated. Use --notification-url with a slack:// URL instead.

Slack Hook URL¶

Deprecated

Use --notification-url with a slack:// URL.

The Slack webhook URL for notifications.

            Argument: --notification-slack-hook-url
Environment Variable: WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL
                Type: String
             Default: None

Slack Identifier¶

Deprecated

Use the botname query parameter in the slack:// URL.

Custom name under which messages are sent.

            Argument: --notification-slack-identifier
Environment Variable: WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER
                Type: String
             Default: watchtower

Slack Channel¶

Deprecated

Configure the channel in your Slack webhook settings or use the appropriate slack:// URL parameters.

A string which overrides the webhook's default channel (optional).

            Argument: --notification-slack-channel
Environment Variable: WATCHTOWER_NOTIFICATION_SLACK_CHANNEL
                Type: String
             Default: None

Slack Legacy Configuration Examples¶

Deprecated

The following examples use deprecated legacy Slack flags. Migrate to --notification-url with a slack:// URL.

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=slack \
  -e WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL="https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy" \
  -e WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER=watchtower-server-1 \
  -e WATCHTOWER_NOTIFICATION_SLACK_CHANNEL=#my-custom-channel \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notifications slack \
  --notification-slack-hook-url "https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy" \
  --notification-slack-identifier watchtower-server-1 \
  --notification-slack-channel "#my-custom-channel"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATIONS: slack
      WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL: "https://hooks.slack.com/services/xxx/yyyyyyyyyyyyyyy"
      WATCHTOWER_NOTIFICATION_SLACK_IDENTIFIER: watchtower-server-1
      WATCHTOWER_NOTIFICATION_SLACK_CHANNEL: "#my-custom-channel"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Microsoft Teams Notifications¶

Deprecated

Legacy MSTeams flags (--notification-msteams-hook) are deprecated. Use --notification-url with a teams:// URL instead.

Example MSTeams Configuration¶

Docker CLIDocker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "teams:?color=%23406170&host=https://default.environment.api.powerplatform.com/powerautomate/automations/direct/workflows/abc123/triggers/manual/paths/invoke?api-version=1&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=XXXXXXXX"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: "teams:?color=%23406170&host=https://default.environment.api.powerplatform.com/powerautomate/automations/direct/workflows/abc123/triggers/manual/paths/invoke?api-version=1&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=XXXXXXXX"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

The following legacy Microsoft Teams configuration options and examples are deprecated and will be removed with the release of Watchtower v2.

Legacy MSTeams Configuration (Deprecated)¶

Deprecated

The following examples use deprecated legacy MSTeams flags.

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=msteams \
  -e WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL="https://default.environment.api.powerplatform.com/powerautomate/automations/direct/workflows/abc123/triggers/manual/paths/invoke?api-version=1&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=XXXXXXXX" \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notifications msteams \
  --notification-msteams-hook "https://default.environment.api.powerplatform.com/powerautomate/automations/direct/workflows/abc123/triggers/manual/paths/invoke?api-version=1&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=XXXXXXXX"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATIONS: msteams
      WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL: "https://default.environment.api.powerplatform.com/powerautomate/automations/direct/workflows/abc123/triggers/manual/paths/invoke?api-version=1&sp=%2Ftriggers%2Fmanual%2Frun&sv=1.0&sig=XXXXXXXX"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Microsoft Teams Configuration Options¶

The following legacy MSTeams flag is deprecated. Use --notification-url with a teams:// URL instead.

MSTeams Hook URL¶

Deprecated

Use --notification-url with a teams:// URL.

The Microsoft Teams Power Automate workflow webhook URL for notifications.

            Argument: --notification-msteams-hook
Environment Variable: WATCHTOWER_NOTIFICATION_MSTEAMS_HOOK_URL
                Type: String
             Default: None

Warning

The value of --notification-msteams-hook must be an absolute URL using the https:// scheme (including the host). Relative URLs and non-HTTPS schemes are rejected at runtime.

Gotify Notifications¶

Deprecated

Legacy Gotify flags (--notification-gotify-url, --notification-gotify-token, --notification-gotify-tls-skip-verify) are deprecated. Use --notification-url with a gotify:// URL instead.

Example Gotify Configuration¶

Docker CLIDocker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "gotify://my.gotify.tld/SuperSecretToken"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: "gotify://my.gotify.tld/SuperSecretToken"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

The following legacy Gotify configuration options and examples are deprecated and will be removed with the release of Watchtower v2.

Legacy Gotify Configuration (Deprecated)¶

Deprecated

The following examples use deprecated legacy Gotify flags.

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATIONS=gotify \
  -e WATCHTOWER_NOTIFICATION_GOTIFY_URL="https://my.gotify.tld/" \
  -e WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN="SuperSecretToken" \
  -e WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY=true \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notifications gotify \
  --notification-gotify-url "https://my.gotify.tld/" \
  --notification-gotify-token "SuperSecretToken" \
  --notification-gotify-tls-skip-verify

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATIONS: gotify
      WATCHTOWER_NOTIFICATION_GOTIFY_URL: "https://my.gotify.tld/"
      WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN: "SuperSecretToken"
      WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY: true
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Gotify Configuration Options¶

The following legacy Gotify flags are deprecated. Use --notification-url with a gotify:// URL instead.

Gotify URL¶

Deprecated

Use --notification-url with a gotify:// URL.

The URL of the Gotify instance.

            Argument: --notification-gotify-url
Environment Variable: WATCHTOWER_NOTIFICATION_GOTIFY_URL
                Type: String
             Default: None

Gotify Token¶

Deprecated

Use --notification-url with a gotify:// URL (token is part of the URL path).

The app token for the Gotify instance.

            Argument: --notification-gotify-token
Environment Variable: WATCHTOWER_NOTIFICATION_GOTIFY_TOKEN
                Type: String
             Default: None

Gotify TLS Skip Verify¶

Deprecated

Use disabletls=yes query parameter in the gotify:// URL.

Skip verification of the server certificate when using TLS.

            Argument: --notification-gotify-tls-skip-verify
Environment Variable: WATCHTOWER_NOTIFICATION_GOTIFY_TLS_SKIP_VERIFY
                Type: Boolean
             Default: false

Signal Notifications¶

Watchtower uses Shoutrrr's signal service to send Signal notifications.

Signal notifications require a Signal API server that can send messages on behalf of a registered Signal account. This is typically done using signal-cli-rest-api or secured-signal-api.

Setting up Signal API Server¶

Phone Number: A dedicated phone number registered with Signal
API Server: A server running signal-cli with REST API capabilities
Account Linking: Linking the server as a secondary device to your Signal account
Optional Security Layer: Authentication and endpoint restrictions via a proxy

The server must be able to receive SMS verification codes during initial setup and maintain a persistent connection to Signal's servers.

Example Signal Configuration¶

Docker CLI (Env Vars)Docker CLI (Flags)Docker Compose

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -e WATCHTOWER_NOTIFICATION_URL=signal://localhost:8080/+1234567890/+0987654321 \
  nickfedor/watchtower

docker run -d \
  --name watchtower \
  -v /var/run/docker.sock:/var/run/docker.sock \
  nickfedor/watchtower \
  --notification-url "signal://localhost:8080/+1234567890/+0987654321"

services:
  watchtower:
    image: nickfedor/watchtower:latest
    environment:
      WATCHTOWER_NOTIFICATION_URL: signal://localhost:8080/+1234567890/+0987654321
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock

Signal URL Format¶

signal://[user:password@]host:port/source_phone/recipient1/recipient2

Parameters¶

host: Signal API server hostname or IP address
port: Signal API server port (default: 8080)
user: Username for HTTP Basic Authentication (optional)
password: Password for HTTP Basic Authentication (optional)
source_phone: Your Signal phone number with country code (e.g., +1234567890)
recipient1, recipient2: Phone numbers or group IDs to send to

TLS Configuration¶

Use signal:// for HTTPS (default, recommended)
Use signal://...?disabletls=yes for HTTP (insecure, for local testing only)

Examples¶

Send to a single phone number:

signal://localhost:8080/+1234567890/+0987654321

Send to multiple recipients:

signal://localhost:8080/+1234567890/+0987654321/+1123456789/group.testgroup

Send to a group:

signal://localhost:8080/+1234567890/group.abcdefghijklmnop=

With authentication:

signal://user:password@localhost:8080/+1234567890/+0987654321

With API token (Bearer auth):

signal://localhost:8080/+1234567890/+0987654321?token=YOUR_API_TOKEN

Using HTTP instead of HTTPS:

signal://localhost:8080/+1234567890/+0987654321?disabletls=yes

Signal Attachments¶

The Signal service supports sending base64-encoded attachments:

shoutrrr send "signal://localhost:8080/+1234567890/+0987654321" \
  "Message with attachment" \
  --attachments "base64data1,base64data2"

Note

Attachments must be provided as base64-encoded data. The API server handles MIME type detection and file handling.