Skip to content

Notifications

Jump to bottom
Will Luck edited this page Mar 3, 2026 · 6 revisions

Notifications

Docker Sentinel delivers notifications through multiple channels. Channels are configured in Settings > Notifications and support independent per-event filtering.

Notification Settings

Providers

Gotify

Self-hosted push notification server.

Setting JSON Key Required
Server URL url Yes
Application token token Yes

Messages are posted to {url}/message with the token in the X-Gotify-Key header. Priority is set to 8 for failures, 5 for all other events.

Slack

Slack incoming webhook integration.

Setting JSON Key Required
Webhook URL webhook_url Yes

Messages use markdown formatting. The webhook URL is obtained from Slack's Incoming Webhooks app configuration.

Discord

Discord webhook integration with rich embeds.

Setting JSON Key Required
Webhook URL webhook_url Yes

Messages are sent as embeds with colour-coded severity: green for success, red for failures, orange for available updates, blue for other events.

Telegram

Telegram Bot API integration.

Setting JSON Key Required
Bot token bot_token Yes
Chat ID chat_id Yes

Create a bot via @BotFather, then use the bot token and the target chat/group ID.

ntfy

Self-hosted or ntfy.sh push notifications.

Setting JSON Key Required
Server URL server Yes
Topic topic Yes
Priority priority No (default: 3)
Access token token No
Username username No
Password password No

Priority maps to ntfy levels: 1=min, 2=low, 3=default, 4=high, 5=urgent. Authentication supports both bearer token and basic auth. Messages use markdown formatting.

Pushover

Push notifications to iOS, Android, and desktop devices.

Setting JSON Key Required
Application token app_token Yes
User key user_key Yes

SMTP (Email)

Send notifications via email.

Setting JSON Key Required
Host host Yes
Port port Yes
From address from Yes
To addresses to Yes (comma-separated)
Username username No
Password password No
TLS mode tls No

TLS mode accepts true, 1, or yes for implicit TLS (port 465). Otherwise STARTTLS is attempted if the server advertises it. Minimum TLS version is 1.2. Multiple recipients are supported as a comma-separated list.

MQTT

Publish events as JSON to an MQTT broker.

Setting JSON Key Required
Broker URL broker Yes
Topic topic Yes
Client ID client_id No (default: docker-sentinel)
Username username No
Password password No
QoS qos No (default: 0)

QoS values: 0 (at most once), 1 (at least once), 2 (exactly once). Values above 2 are clamped to 0.

MQTT Payload Format

{
  "type": "update_available",
  "container_name": "nginx",
  "old_image": "nginx:1.24",
  "new_image": "nginx:1.25",
  "error": "",
  "timestamp": "2025-01-15T10:30:00Z"
}

Apprise

Relay notifications through an Apprise API server. Apprise supports 100+ notification services.

Setting JSON Key Required
Apprise API URL url Yes
Tag tag No
Service URLs urls No (required if no tag)

If tag is set, the notification is posted to {url}/notify/{tag}. Otherwise, urls must contain Apprise service URL(s) and the notification is posted to {url}/notify/.

Sentinel event types are mapped to Apprise notification types: success for successful updates/rollbacks, failure for failures, info for everything else.

Webhook (Generic)

Posts the full event as a JSON payload to any HTTP(S) endpoint.

Setting JSON Key Required
URL url Yes
Custom headers headers No

Custom headers are sent with every request. Use these for authentication (e.g. Authorization: Bearer ...). Only http and https schemes are accepted.

Log

Always enabled. Writes every event as a structured log line at INFO level. This serves as a guaranteed notification record regardless of provider configuration.

Event Types

Event Fired when
update_available A newer image digest is found for a tracked container
version_available A newer tagged version is found (e.g. v1.2.3 to v1.2.4)
update_started An update pull and container restart has begun
update_succeeded The container restarted successfully with the new image
update_failed The update attempt failed
rollback_succeeded A rollback completed successfully
rollback_failed A rollback attempt failed
container_state A container's running state changed (started/stopped)
digest Daily digest summary of pending updates

Each channel can be configured to receive any subset of these events. Channels with no event filter receive all events.

Notification Modes

Controls how often notifications fire per container. The global default applies unless a container has an override.

Mode Behaviour
Immediate + summary Alert when an update is detected; include in digest. Deduplication prevents re-alerting for the same version.
Every scan Alert every scan an update is found, even if already notified. No digest.
Summary only No immediate alerts. Include in the daily digest only.
Silent No notifications for this container.

Set globally from Settings > Notification Behaviour, or per-container from the container detail page or Settings > Per-Container Overrides.

Daily Digest

Consolidated report of all pending updates sent at a scheduled time.

Setting Default Description
Enabled false Toggle digest delivery
Time 09:00 Local time of day for delivery
Frequency Daily How often the digest fires

Trigger a digest immediately:

POST /api/digest/trigger

A dismissible banner appears on the dashboard when updates are pending:

POST /api/digest/banner/dismiss

Deduplication

Sentinel tracks which update notifications have been sent and suppresses re-alerts for the same image version. This prevents repeated notifications if a container restarts without a version change.

Clear deduplication state to allow alerts to fire again for currently-known versions:

DELETE /api/notify-states

Notification Templates

Notification messages support Go text/template syntax. Custom templates can be set per event type. When no custom template is defined, the default format is used.

Available Template Variables

Variable Description
{{.ContainerName}} Container name
{{.OldImage}} Previous image reference
{{.NewImage}} New image reference
{{.OldDigest}} Previous image digest
{{.NewDigest}} New image digest
{{.Error}} Error message (empty on success)
{{.Type}} Event type name
{{.Timestamp}} Event timestamp
{{.Title}} Human-readable title
{{.Emoji}} Event emoji
{{.Severity}} Event severity level

Preview a template with sample data:

POST /api/settings/notification-templates/preview
Content-Type: application/json

{
  "template": "Container {{.ContainerName}} has a new image: {{.NewImage}}",
  "event_type": "update_available"
}

MQTT Home Assistant Auto-Discovery

Sentinel can publish Home Assistant MQTT auto-discovery payloads. When configured, it creates:

  • Binary sensors per container (ON when an update is available, OFF otherwise)
  • A pending count sensor showing the total number of pending updates

Discovery Topics

Entity Config topic State topic
Per-container update sensor homeassistant/binary_sensor/sentinel_{name}/config sentinel/containers/{name}/update_available
Pending update count homeassistant/sensor/sentinel_pending/config sentinel/pending_count

HA Device

All entities are grouped under a single Home Assistant device:

Property Value
Identifiers docker_sentinel
Name Docker Sentinel
Manufacturer Docker Sentinel
Model Container Update Monitor

Discovery configs are published with QoS 1 and the retain flag set so Home Assistant picks them up on restart.

Configuration

MQTT Home Assistant discovery shares the MQTT channel's broker connection. Configure an MQTT notification channel with the same broker your Home Assistant instance uses.

Inbound Webhooks

Sentinel accepts inbound webhook notifications from container registries to trigger immediate scans when an image is pushed.

Supported Formats

Source Discriminator Parsed fields
Docker Hub push_data key present repository.repo_name, push_data.tag
GHCR (GitHub Packages) package key present package.namespace, package.name, package_version.container_metadata.tag.name
Generic image key present image, tag (or image:tag combined)

Docker Hub Payload

{
  "push_data": {"tag": "latest"},
  "repository": {"repo_name": "library/nginx"}
}

GHCR Payload

{
  "action": "published",
  "package": {
    "name": "my-app",
    "namespace": "username",
    "package_type": "container",
    "package_version": {
      "container_metadata": {
        "tag": {"name": "v1.0.0"}
      }
    }
  }
}

Generic Payload

{"image": "nginx", "tag": "v1.2.3"}

Or combined:

{"image": "nginx:v1.2.3"}

Unrecognised JSON payloads are accepted but returned with source "unknown".

Adding a Channel

  1. Go to Settings > Notifications.
  2. Click Add Channel.
  3. Select provider and fill in the required credentials.
  4. Select which events the channel should receive (leave empty for all).
  5. Click Test to send a test notification before saving.
  6. Click Save.

Multiple channels of the same provider type can be added (e.g. two Discord webhooks targeting different servers). Channels can be edited, deleted, enabled, and disabled from the same list.

Per-Container Overrides

Set from:

  • Container Detail page: notification mode selector
  • Settings > Per-Container Overrides: table view of all overrides
  • API: POST /api/containers/{name}/notify-pref

Request body:

{
  "mode": "immediate | every_scan | summary | silent"
}

View all current overrides:

GET /api/settings/container-notify-prefs

Legacy Environment Variables

These remain supported for backwards compatibility. The web UI is recommended for new setups.

Variable Provider
SENTINEL_GOTIFY_URL Gotify
SENTINEL_GOTIFY_TOKEN Gotify
SENTINEL_WEBHOOK_URL Webhook
SENTINEL_WEBHOOK_HEADERS Webhook

Outbound Webhook Payload Format

The generic webhook provider sends the full event as JSON:

{
  "type": "update_available",
  "container_name": "nginx",
  "old_image": "nginx:1.24",
  "new_image": "nginx:1.25",
  "old_digest": "sha256:abc123...",
  "new_digest": "sha256:def456...",
  "error": "",
  "container_names": [],
  "timestamp": "2025-01-15T10:30:00Z"
}

Home

Getting Started

Using Sentinel

Multi-Host

Security

Reference

Clone this wiki locally