Actions & Notifications

Action and notification providers are enabled using environment variables.

DD_ACTION_{{ trigger_type }}_{{ trigger_name }}_{{ trigger_configuration_item }}=XXX
DD_NOTIFICATION_{{ trigger_type }}_{{ trigger_name }}_{{ trigger_configuration_item }}=XXX

Environment variable prefixes

Three prefixes are supported for trigger configuration:

Use DD_ACTION_* for update-action providers (Docker, Docker Compose, Command) and DD_NOTIFICATION_* for messaging providers (Slack, SMTP, Discord, etc.). The legacy DD_TRIGGER_* prefix still maps to the same configuration during the v1.6 compatibility window, but its error-level migration signal is intentionally loud; migrate it before v1.7.

When the same trigger property is set under multiple prefixes, the merge priority is DD_NOTIFICATION_* > DD_ACTION_* > DD_TRIGGER_* (highest wins).

Migrating trigger prefixes

The following example shows a typical before/after migration for a Docker + Slack setup.

Before (deprecated DD_TRIGGER_* form):

# .env — legacy form (deprecated in v1.5.0, removed in v1.7.0)
DD_TRIGGER_DOCKER_LOCAL_PRUNE=true
DD_TRIGGER_SLACK_MYSLACK_URL=https://hooks.slack.com/services/T000/B000/xxxx
DD_TRIGGER_SMTP_GMAIL_HOST=smtp.gmail.com
DD_TRIGGER_SMTP_GMAIL_PORT=465

Run the migration (add --dry-run to preview without writing):

node dist/index.js config migrate --source trigger

After (canonical prefixes):

# .env — canonical form
# Update-action triggers use DD_ACTION_*
DD_ACTION_DOCKER_LOCAL_PRUNE=true
# Messaging/notification triggers use DD_NOTIFICATION_*
DD_NOTIFICATION_SLACK_MYSLACK_URL=https://hooks.slack.com/services/T000/B000/xxxx
DD_NOTIFICATION_SMTP_GMAIL_HOST=smtp.gmail.com
DD_NOTIFICATION_SMTP_GMAIL_PORT=465

Available triggers

Update actions:

• Docker -- Update containers via the Docker Engine API
• Docker Compose -- Update containers managed by Docker Compose
• Command -- Execute a shell command

Messaging & notifications:

• Apprise -- Multi-provider notification relay
• Discord -- Discord webhook
• Google Chat -- Google Chat webhook
• Gotify -- Gotify push notification
• HTTP -- Generic HTTP request
• IFTTT -- IFTTT webhook
• Kafka -- Apache Kafka topic
• Matrix -- Matrix room message
• Mattermost -- Mattermost webhook
• MQTT -- MQTT topic
• ntfy -- ntfy push notification
• Pushover -- Pushover notification
• Rocket.Chat -- Rocket.Chat webhook
• Slack -- Slack webhook
• SMTP -- Email notification
• Teams -- Microsoft Teams webhook
• Telegram -- Telegram bot message

Common trigger configuration

All implemented triggers, in addition to their specific configuration, also support the following common configuration variables. The table uses DD_NOTIFICATION_{trigger_type}_{trigger_name}_* for notification triggers and DD_ACTION_{trigger_type}_{trigger_name}_* for action triggers (see Environment variable prefixes above). For brevity the rows below show the DD_NOTIFICATION_* form; replace with DD_ACTION_* for Docker, Docker Compose, and Command triggers.

Threshold reference

The semver thresholds can be suffixed with -no-digest to exclude digest-only updates. Supported no-digest variants are major-no-digest, major-only-no-digest, minor-no-digest, minor-only-no-digest, and patch-no-digest. Updates with an unknown update kind (e.g. created-date-only changes) are passed through when threshold=all, but filtered out for all other threshold values.

Notes

• RESOLVENOTIFICATIONS is currently implemented for Gotify (auto-deletes the notification message after a successful update). Other providers can be extended to support it.
• Some messaging triggers (Slack, Telegram, Teams, Matrix, Mattermost, Rocket.Chat, Google Chat) also support DISABLETITLE (default false) to send only the body without a title line.
• You can set DD_NOTIFICATION_{trigger_type}_THRESHOLD to define a default threshold for all triggers of the same type, e.g. DD_NOTIFICATION_NTFY_THRESHOLD=minor (or DD_ACTION_{trigger_type}_THRESHOLD for action triggers).
• Triggers are executed by ascending ORDER; when two triggers have the same ORDER, they are sorted by trigger id.
• Triggers sharing the same trigger name (e.g. docker.update and discord.update) can share THRESHOLD; if exactly one threshold value is defined among them, that value is used for the others unless they override it explicitly.
• Setting ONCE=false with MODE=batch gives a report with all pending updates on every run.
• DIGESTCRON is validated with cron.validate() at registration time. An invalid cron expression causes a startup error with a descriptive message — the trigger will not be registered.
• MODE=digest accumulates update events in an in-memory buffer and flushes them as a single batch notification on the DIGESTCRON schedule. If the same container has multiple updates within the window, only the latest is included. Containers that are updated before the digest fires are automatically evicted from the buffer. Useful for daily email digests: DD_NOTIFICATION_SMTP_GMAIL_MODE=digest + DD_NOTIFICATION_SMTP_GMAIL_DIGESTCRON=0 8 * * *.
• MODE=batch+digest enables both modes simultaneously — immediate batch emails on each scan cycle plus a scheduled digest summary. Requires DIGESTCRON to be set.
• Note: Digest and batch modes still depend on the update-available notification rule being enabled (see below). If the trigger is excluded from update-available routing, no events reach the buffer.
• SECURITYMODE governs security-alert delivery independently of MODE. A trigger may legitimately want MODE=batch for update notifications and SECURITYMODE=digest for security findings. Digest and batch+digest modes buffer alerts per-scan-cycle (keyed by cycleId) and flush one summary per cycle on completion. Cycles with zero findings never emit. See the Security Hardening Guide for an end-to-end example.
• SECURITYDIGESTTITLE and SECURITYDIGESTBODY use the same sandboxed ${...} template renderer as other trigger templates. They substitute scan.* variables and are not evaluated as JavaScript.
• Scheduled scans do not emit security-alert events by default. Set DD_SECURITY_SCAN_NOTIFICATIONS=true to opt in. On-demand scans (UI button, POST /api/v1/containers/:id/scan, POST /api/v1/containers/scan-all) always emit.
• Notification deduplication (ONCE=true) is now persisted in the notifications_history store collection, so once=true dedup survives restarts. Previously the dedup state was lost on container restart, causing previously-suppressed notifications to re-fire.
• Digest and batch-retry buffers enforce a 5,000-entry cap and a 7-day retention limit. Entries exceeding the cap or age are evicted before the next digest flush.
• When release notes bodies are truncated to fit within the notification body limit, the truncated body is marked with a trailing … ellipsis so recipients know the notes continue at the source URL.

Notification Rules

Notification rules control which events fire which triggers. Each rule corresponds to an event type and has an enabled flag and an optional list of trigger IDs.

The in-app bell has audit-backed controls for update-available, update-applied, update-failed, security-alert, agent-disconnect, and container-unhealthy. agent-reconnect remains a delivery rule but does not expose a bell toggle because that action is not part of the bell's audit query. Notification-delivery failures are always included. Agent status changes refresh disconnect entries; health-only container changes propagate across local and agent paths, and a replayable health-transition event is ordered after audit processing so the bell refetch sees any newly inserted unhealthy row.

Dispatch behavior:

• update-available -- when its trigger list is empty, all notification triggers fire (legacy default). Once you assign specific triggers, only those fire.
• update-applied, update-failed, security-alert -- when their trigger list is empty, all notification triggers fire (same permissive default as update-available). Once you assign specific triggers, only those fire.
• agent-disconnect, agent-reconnect -- disabled by default. Enable them and assign triggers to receive disconnect/reconnect alerts. When their trigger list is empty, all notification triggers fire. These events always fire regardless of the threshold setting.
• container-unhealthy -- disabled by default. Enable it and assign triggers to receive container health alerts. When its trigger list is empty, all notification triggers fire. This event always fires regardless of the threshold setting.

Rules are managed via GET /api/v1/notifications and PATCH /api/v1/notifications/:id, or through the Notifications view in the UI. The rule detail panel keeps three related controls together:

• Delivery routing — enabled and triggers decide whether the event is delivered and which configured notification providers receive it.
• In-app bell — bellEnabled includes or excludes an audit-backed event category from the header bell. For update-available, bellThreshold can show all updates, major only, minor-and-up, or patch-and-up. Rules without bell audit coverage hide these controls.
• Template overrides — choose a configured notification trigger and override its simpleTitle, simpleBody, and/or batchTitle for this rule. Empty fields inherit the trigger's configured/default template. Preview renders the draft with representative event data before saving.

Overrides are keyed by canonical trigger ID, so the same event can use different copy for Slack, SMTP, ntfy, or any other configured notification provider. They use the same sandboxed ${...} syntax and variables documented in Template variable reference. The preview API is POST /api/v1/notifications/:id/preview; see the Notification rules API for its request shape.

Event Types

Beyond the classic update-available event, triggers can fire on additional events:

• update-applied -- fires after a container is successfully updated by a Docker or Docker Compose trigger. Useful for audit or confirmation notifications.
• update-failed -- fires when an update fails or is rolled back. Carries the container name and error message.
• security-alert -- fires when the Update Bouncer detects critical or high vulnerabilities during a pre-update scan. Includes a vulnerability summary.
• agent-disconnect -- fires when a remote agent loses its connection. This event skips threshold checks (always fires).
• agent-reconnect -- fires when a remote agent reconnects after losing connection. Only fires on true reconnects, not the initial startup connection. This event skips threshold checks (always fires).
• container-unhealthy -- fires when a container's Docker health check transitions into the unhealthy state. Does not fire for containers with no HEALTHCHECK configured, and does not fire again while the container remains continuously unhealthy -- except when the container restarts (new boot) while unhealthy, which counts as a new episode and fires again. This event skips threshold checks (always fires).

Notification Outbox

Drydock uses a durable notification outbox to persist and retry failed notification deliveries. When a trigger call fails (network error, provider down, etc.), the delivery intent is saved and retried with exponential backoff and jitter rather than being silently dropped.

Default behavior:

• Max attempts: 5. After 5 failed attempts the entry moves to dead-letter status.
• Backoff: 30 s base, doubles per attempt, capped at 5 minutes. Up to 5 s jitter per retry.
• TTL: 30 days. Delivered and dead-letter entries older than 30 days are purged automatically.

API:

UI: The Notification Outbox page (Settings → Notification Outbox, route /notifications/outbox) shows tabs for Dead-letter, Pending, and Delivered entries with Retry and Discard actions.

Template Variable Reference

Template strings use ${expression} placeholders. Drydock provides two sets of variables depending on the trigger mode.

Simple mode variables

Batch mode variables

Expression syntax

Inside ${...} you can use:

• Property paths -- container.updateKind.kind
• Method calls -- container.name.substring(0, 15) (see allowed methods below)
• Ternary -- container.result.link ? container.result.link : "no link"
• Logical AND -- container.result && container.result.link
• String concatenation -- "Version: " + container.updateKind.remoteValue
• String and number literals -- "hello", 42

Allowed string methods: substring, slice, toLowerCase, toUpperCase, trim, trimStart, trimEnd, replace, split, indexOf, lastIndexOf, startsWith, endsWith, includes, charAt, padStart, padEnd, repeat, toString.

Examples

services:
  drydock:
    image: codeswhat/drydock
    ...
    environment:
      - DD_NOTIFICATION_SMTP_GMAIL_SIMPLETITLE=Container $${container.name} can be updated
      - DD_NOTIFICATION_SMTP_GMAIL_SIMPLEBODY=Container $${container.name} can be updated from $${container.updateKind.localValue.substring(0, 15)} to $${container.updateKind.remoteValue.substring(0, 15)}

docker run \
  -e 'DD_NOTIFICATION_SMTP_GMAIL_SIMPLETITLE=Container ${container.name} can be updated' \
  -e 'DD_NOTIFICATION_SMTP_GMAIL_SIMPLEBODY=Container ${container.name} can be updated from ${container.updateKind.localValue.substring(0, 15)} to ${container.updateKind.remoteValue.substring(0, 15)}' \
  codeswhat/drydock