Registry Webhooks

Registry push notifications can request an immediate check of matching watched containers. WUD queries the configured registry provider, stores the normal update result, and evaluates existing triggers. Scheduled watcher polling remains enabled as reconciliation when notifications are lost or checks fail.

Providers based on Docker Registry V2 accept the Docker Distribution notification format, including GitLab Self-Managed registries. This format is different from GitLab project push webhooks. Configuring GitLab registry notifications requires registry administration access; a GitLab.com project webhook does not provide this integration.

Configuration

Enable incoming notifications on an existing configured registry instance by setting its webhook token. Environment names are normalized to lowercase, so a GitLab registry named LOCAL uses POST /api/registries/gitlab.local/events. The endpoint uses the full registry identifier shown by WUD, including its provider and instance name.

Variable	Type	Default	Description
WUD_REGISTRY_GITLAB_LOCAL_WEBHOOK_TOKEN	String	None	Nonempty shared webhook secret; omitting it disables incoming notifications for this registry instance.

services:
  whatsupdocker:
    image: getwud/wud
    environment:
      WUD_REGISTRY_GITLAB_LOCAL_URL: "https://registry.example.com"
      WUD_REGISTRY_GITLAB_LOCAL_AUTHURL: "https://gitlab.example.com"
      WUD_REGISTRY_GITLAB_LOCAL_WEBHOOK_TOKEN: "${WUD_WEBHOOK_TOKEN}"

Send Authorization: Bearer <WUD_WEBHOOK_TOKEN> on every request. This endpoint uses its webhook secret independently of UI/API authentication. Keep the secret private and expose the receiver through HTTPS. Registry read credentials still belong in the GitLab registry configuration; the webhook token does not grant registry access.

For another supported provider, use WUD_REGISTRY_{PROVIDER}_{NAME}_WEBHOOK_TOKEN and POST /api/registries/{provider}.{name}/events. The provider must support the incoming notification format and the sender must allow a custom Authorization header.

Configure GitLab notifications

Follow GitLab's container registry notification administration guide. For a Linux package installation, add a WUD entry to registry['notifications'] in /etc/gitlab/gitlab.rb, preserving existing notification endpoints:

{
  'name' => 'wud-local',
  'url' => 'https://wud.example.com/api/registries/gitlab.local/events',
  'timeout' => '2s',
  'maxretries' => 5,
  'backoff' => '1s',
  'headers' => {
    'Authorization' => ['Bearer replace-with-your-wud-receiver-secret']
  }
}

Replace the secret with the same value configured in WUD, then run sudo gitlab-ctl reconfigure. Preserve GitLab's own notification endpoint and its existing authorization secret. For other installation types, configure the equivalent additional endpoint in the registry's notification configuration.

Payload and matching

The receiver accepts application/json and application/vnd.docker.distribution.events.v2+json. A tagged manifest push looks like:

{
  "events": [
    {
      "action": "push",
      "target": {
        "mediaType": "application/vnd.docker.distribution.manifest.v2+json",
        "repository": "apps/my-container",
        "tag": "latest",
        "digest": "sha256:aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "url": "https://registry.example.com/v2/apps/my-container/manifests/latest"
      },
      "request": { "host": "registry.example.com" }
    }
  ]
}

WUD derives the registry host from target.url, or from request.host when no URL is present. It handles Docker and OCI manifest and index pushes with a tag and SHA-256 digest. Pulls, deletes, layer pushes, and untagged manifests are ignored.

Only containers already known to WUD and assigned to the addressed registry instance with the same registry host, repository, and current tag are checked. A push to apps/my-container:latest does not immediately check a container running apps/my-container:1.0; polling still discovers other candidate tags. Another configured registry instance's containers are not selected, even if their image names match. The pushed digest is a hint and a deduplication key: WUD reads remote registry metadata rather than trusting the event as an update command.

Existing policies still apply

The watcher refreshes workload discovery and uses its normal check and report path for matching containers. All existing settings remain effective: wud.watch, wud.watch.digest, wud.tag.include, wud.tag.exclude, wud.trigger.include, wud.trigger.exclude, trigger.includeByDefault, trigger.auto, and trigger.dryrun.

For mutable tags such as latest, enable wud.watch.digest to detect a changed digest. With WUD_TRIGGER_DOCKERCOMPOSE_LOCAL_INCLUDEBYDEFAULT=false, the Compose trigger still requires the container's explicit opt-in:

services:
  my-container:
    image: registry.example.com/apps/my-container:latest
    labels:
      wud.watch: "true"
      wud.watch.digest: "true"
      wud.trigger.include: "dockercompose.local"

Configure the Docker Compose trigger normally. Receiving a notification only requests a check; it does not directly update a container or override trigger eligibility.

Responses and reliability

• 202: hints accepted for asynchronous processing, with an accepted count. This does not guarantee a completed check or update. Unknown images and ignored events do no work.
• 400: malformed notification or unsupported notification format; 413: request exceeds 256 KiB.
• 401: missing or incorrect webhook authorization; 404: unknown registry instance or webhook token not configured.
• 429: pending hint capacity exceeded; retry later.

Requests contain at most 100 events. Pending and recently completed hints are bounded to 1,000 entries. Checks are serialized. Repeated registry-instance/host/repository/tag/digest hints are suppressed while pending and for 60 seconds after successful processing. Deduplication is in memory and resets on restart.

Failed registry checks are logged and are not marked successfully processed; a later delivery can retry. Because processing begins after the 202 response, GitLab's delivery retries do not automatically retry an already accepted registry-query failure. Keep scheduled polling enabled as fallback.