Version: 9.x

Triggers

Triggers perform automated actions (such as sending notifications or executing updates) whenever a new container version is discovered.

Triggers are configured using environment variables following this naming pattern:

WUD_TRIGGER_{trigger_type}_{trigger_name}_{configuration_item}=value

Multiple Instances Supported

You can configure multiple triggers of the same type (for example, multiple SMTP or Discord destinations). Simply assign each one a distinct {trigger_name} identifier (e.g. WUD_TRIGGER_DISCORD_DEV_URL, WUD_TRIGGER_DISCORD_PROD_URL).

📂 Trigger Categories

WUD supports 30+ triggers organized into three functional categories:

⚡ Auto-Update & Orchestration: Automatically pull new images and recreate containers or trigger orchestrator restarts (Docker, Docker Compose, Nomad).
🔔 Notifications & Chat: Send rich alert messages with update details (Apprise, Bark, Discord, Gotify, IFTTT, Matrix, Mattermost, Ntfy, Opsgenie, PagerDuty, Prowl, Pushover, Rocket.Chat, Signal, Slack, SMTP Email, Telegram, WhatsApp, Zulip).
🛠 Webhooks & Automation Pipelines: Integrate with custom automation flows, Home Assistant, and message brokers (AMQP (RabbitMQ), Command, GitHub Actions, GitLab CI, Home Assistant, HTTP Webhooks, Kafka, MQTT, NATS, Uptime Kuma).

Common Trigger Configuration

In addition to provider-specific settings, all triggers support the following common configuration variables:

WUD_TRIGGER_{trigger_type}_{trigger_name}_AUTO

Optionalbooleandefault: true

Whether to execute the trigger automatically (false requires manual execution via UI or API)

WUD_TRIGGER_{trigger_type}_{trigger_name}_BATCHTITLE

Optionalstringdefault: ${containers.length} updates available

Template used to render the notification title in batch mode

Allowed values:String template with `${count}`, `${hostname}`, `${watcher}` placeholders

WUD_TRIGGER_{trigger_type}_{trigger_name}_EVENTS

Optionalstringdefault: available

Subscribed container update lifecycle events. Can be overridden per container via wud.trigger.events or wud.trigger.<name>.events.

Allowed values:Comma-separated string of `available`, `pre`, `success`, `failure`, `rollback`

WUD_TRIGGER_{trigger_type}_{trigger_name}_FAILUREBODY

Optionalstringdefault: Container ${container.name} update failed: ${error}

Template used to render the notification body when an update fails

Allowed values:JS string template with `container` object and `error` string

WUD_TRIGGER_{trigger_type}_{trigger_name}_FAILURETITLE

Optionalstringdefault: Update FAILED for ${container.name}

Template used to render the notification title when an update fails

Allowed values:JS string template with `container` object

WUD_TRIGGER_{trigger_type}_{trigger_name}_INCLUDEBYDEFAULT

Optionalbooleandefault: true

Associate trigger with all containers by default (false makes it opt-in via container labels or wud.trigger.include)

WUD_TRIGGER_{trigger_type}_{trigger_name}_MODE

Optionalenumdefault: simple

Execution mode: trigger individually per container or batch all available updates into a single notification

Allowed values:`simple`, `batch`

WUD_TRIGGER_{trigger_type}_{trigger_name}_ONCE

Optionalbooleandefault: true

Execute trigger only once per detected update (prevents duplicate alerts on consecutive runs)

WUD_TRIGGER_{trigger_type}_{trigger_name}_ONDIGEST

Optionalbooleandefault: true

Enable or disable notifications when only the image digest has changed (without semver tag bump)

WUD_TRIGGER_{trigger_type}_{trigger_name}_ROLLBACKBODY

Optionalstringdefault: Container ${name} was rolled back from ${newImageRef} to ${oldImageRef} (reason: ${reason}).

Template used to render the body of a rollback notification (both success and failure are produced by the same template)

Allowed values:JS string template with `name`, `scope`, `status`, `reason`, `oldImageRef`, `newImageRef`, `archiveName`, `error_step`, `error_message`, `services` and `container`

WUD_TRIGGER_{trigger_type}_{trigger_name}_ROLLBACKTITLE

Optionalstringdefault: Rollback of ${name}

Template used to render the title of a rollback notification

Allowed values:JS string template with `name`, `scope`, `status`, `reason`, `oldImageRef`, `newImageRef`, `archiveName`, `error_step`, `error_message`, `services` and `container`

WUD_TRIGGER_{trigger_type}_{trigger_name}_SIMPLEBODY

Optionalstringdefault: Container ${container.name} running with ${container.updateKind.kind} ${container.updateKind.localValue} can be updated to ${container.updateKind.kind} ${container.updateKind.remoteValue}${container.result && container.result.link ? "\\n" + container.result.link : ""}

Template used to render the notification body in simple mode

Allowed values:JS string template with `container` object

WUD_TRIGGER_{trigger_type}_{trigger_name}_SIMPLETITLE

Optionalstringdefault: New ${container.updateKind.kind} found for container ${container.name}

Template used to render the notification title in simple mode

Allowed values:JS string template with `container` object

WUD_TRIGGER_{trigger_type}_{trigger_name}_SUCCESSBODY

Optionalstringdefault: Container ${container.name} has been successfully updated.

Template used to render the notification body when an update is successful

Allowed values:JS string template with `container` object

WUD_TRIGGER_{trigger_type}_{trigger_name}_SUCCESSTITLE

Optionalstringdefault: Update SUCCESS for ${container.name}

Template used to render the notification title when an update is successful

Allowed values:JS string template with `container` object

WUD_TRIGGER_{trigger_type}_{trigger_name}_THRESHOLD

Optionalenumdefault: all

Minimum semver version bump required to fire the trigger

Allowed values:`all`, `major`, `major-only`, `minor`, `minor-only`, `patch`

Threshold Values

all: Executes the trigger for all update types (including digests).
major: Executes the trigger for major, minor, or patch semver updates.
major-only: Executes the trigger only for major semver updates.
minor: Executes the trigger for minor or patch semver updates.
minor-only: Executes the trigger only for minor semver updates.
patch: Executes the trigger only for patch semver updates.

📝 Template Placeholders & Variables

Trigger titles and bodies (SIMPLETITLE, SIMPLEBODY, BATCHTITLE, BATCHBODY, SUCCESSTITLE, SUCCESSBODY, FAILURETITLE, FAILUREBODY, ROLLBACKTITLE, ROLLBACKBODY) are evaluated as JavaScript template literals against the container update data.

Simple Mode Variables

In simple mode (MODE=simple), all container properties are accessible via the container object:

Property	Description	Example
`container.name`	Monitored container name	`nginx`
`container.watcher`	Watcher or host name that discovered the container	`local`, `host1`, `prod`
`container.id`	Unique container ID	`9d5fa8b3c10a`
`container.updateKind.kind`	Update category (`tag` or `digest`)	`tag`
`container.updateKind.localValue`	Current local tag or short digest	`1.25.0`
`container.updateKind.remoteValue`	Target remote tag or short digest	`1.26.0`
`container.updateKind.semverDiff`	Semver difference level	`major`, `minor`, `patch`
`container.isOfficial`	Boolean indicating if the image is an official Docker Hub image (`true` or `false`)	`true`
`container.documentationUrl`	Documentation URL (from label or Docker Hub official default)	`https://hub.docker.com/_/postgres`
`container.changelogUrl`	Changelog or release notes URL (from label)	`https://github.com/postgres/postgres/releases`
`container.upstreamUrl`	Upstream source code repository URL (from label)	`https://github.com/postgres/postgres`
`container.link`	Preserved link fallback (pointing to `documentationUrl` or `upstreamUrl`)	`https://...`
`container.result.link`	Changelog or registry link (if available)	`https://...`

Multi-Host Notifications

When monitoring multiple Docker daemons or remote hosts using distinct watchers (e.g. WUD_WATCHER_HOST1_..., WUD_WATCHER_HOST2_...), include $${container.watcher} in your SIMPLEBODY or SIMPLETITLE to identify which host discovered the update.

Batch Mode Variables

In batch mode (MODE=batch), multiple container updates are grouped into a single notification:

Property	Description	Example
`containers`	Array of updated `container` objects	`[ { name: 'web', ... }, ... ]`
`containers.length`	Total number of containers with available updates	`3`
`count`	Shorthand alias for `containers.length`	`3`
`hostname`	Host name from `WUD_LOG_HOSTNAME` or system hostname	`server1`
`watcher`	Common watcher name across containers (or first watcher)	`local`, `host1`

🎯 Container Trigger Filtering & Precedence

You can control which triggers execute for a given container by attaching labels (or annotations/metadata) directly to your workload.

Precedence Order

When evaluating whether a trigger applies to a container, WUD checks rules in the following 3-level order:

Level	Rule	Example Label	Effect
1. Specific Trigger (Highest)	`wud.trigger.<type>.<name>.enabled`	`wud.trigger.docker.autoupdate.enabled=true`	Explicitly enables or disables this specific trigger instance, ignoring all lower-level settings.
2. Trigger Type	`wud.trigger.<type>.enabled`	`wud.trigger.docker.enabled=false`	Enables or disables all triggers of that type (e.g. all `docker` updaters or all `telegram` notifications).
3. Global Filters & Defaults	`wud.trigger.include` / `wud.trigger.exclude` / `INCLUDEBYDEFAULT`	`wud.trigger.include=docker.autoupdate`	Evaluates legacy include/exclude lists. If no labels apply, falls back to the trigger's `INCLUDEBYDEFAULT` configuration.

Supported Prefixes

Labels can be formatted using wud.trigger.<...> (Docker / Docker Compose), getwud.app/trigger.<...> (Kubernetes, Swarm, Nomad), or trigger.<...>.

Concrete Use Case: Targeted Auto-Update Opt-In

A common workflow is to keep auto-updates disabled globally, while selectively enabling auto-updates for specific containers:

Configure your auto-update trigger with INCLUDEBYDEFAULT=false:

# Update trigger is registered, but does NOT run on containers by default
WUD_TRIGGER_DOCKER_AUTOUPDATE_AUTO=true
WUD_TRIGGER_DOCKER_AUTOUPDATE_INCLUDEBYDEFAULT=false

# Notification triggers remain enabled by default
WUD_TRIGGER_TELEGRAM_NOTIFY_AUTO=true
WUD_TRIGGER_TELEGRAM_NOTIFY_INCLUDEBYDEFAULT=true

Opt-in specific containers using the granular label:

services:
  web:
    image: nginx:latest
    labels:
      # Only this container is auto-updated; telegram notifications still fire for all containers
      - "wud.trigger.docker.autoupdate.enabled=true"

  database:
    image: postgres:16
    # No label: will receive telegram notification, but will NOT be auto-updated

Granular Labels vs wud.trigger.include

The legacy wud.trigger.include label acts as an exclusive allowlist: setting wud.trigger.include=docker.autoupdate would disable all other triggers (including Telegram notifications) for that container. Granular labels (wud.trigger.<type>.<name>.enabled=true|false) allow targeted opt-in or opt-out without interfering with other triggers.

🚀 Examples

Customizing Notification Content

Docker Compose
Docker

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      - WUD_TRIGGER_SMTP_GMAIL_SIMPLETITLE=Container $${container.name} can be updated
      - WUD_TRIGGER_SMTP_GMAIL_SIMPLEBODY=Container $${container.name} on host $${container.watcher} can be updated from $${container.updateKind.localValue} to $${container.updateKind.remoteValue}

docker run \
  -e 'WUD_TRIGGER_SMTP_GMAIL_SIMPLETITLE=Container ${container.name} can be updated' \
  -e 'WUD_TRIGGER_SMTP_GMAIL_SIMPLEBODY=Container ${container.name} on host ${container.watcher} can be updated from ${container.updateKind.localValue} to ${container.updateKind.remoteValue}' \
  getwud/wud

📂 Trigger Categories​

Common Trigger Configuration​

Threshold Values​

📝 Template Placeholders & Variables​

Simple Mode Variables​

Batch Mode Variables​

🎯 Container Trigger Filtering & Precedence​

Precedence Order​

Concrete Use Case: Targeted Auto-Update Opt-In​

🚀 Examples​

Customizing Notification Content​

📂 Trigger Categories

Common Trigger Configuration

Threshold Values

📝 Template Placeholders & Variables

Simple Mode Variables

Batch Mode Variables

🎯 Container Trigger Filtering & Precedence

Precedence Order

Concrete Use Case: Targeted Auto-Update Opt-In

🚀 Examples

Customizing Notification Content