projects/Dockers/docker-webhook-updater/README.md

Docker Webhook Updater

A Docker container that monitors a Docker image for updates and triggers a webhook when a new version is detected.

Features

• Monitors Docker images from any registry (Docker Hub, GHCR, Quay.io, custom registries)
• Detects image updates by comparing SHA256 digests
• Triggers webhook with bearer token authentication
• Persistent SHA storage across container restarts
• Configurable check interval

Environment Variables

Variable	Description	Required	Example
DOCKER_REPO_URL	Docker registry URL	Yes	docker.io, ghcr.io, quay.io, or custom registry
DOCKER_IMAGE	Full image name with tag	Yes	username/image:latest, library/nginx:1.25
WEBHOOK_URL	URL to call when image is updated	Yes	https://example.com/webhook
WEBHOOK_TOKEN	Bearer token for webhook authentication	Yes	your-secret-token
CHECK_INTERVAL	Seconds between checks (default: 300)	No	600

Usage

Docker Hub Example

docker run -d \
  -e DOCKER_REPO_URL=docker.io \
  -e DOCKER_IMAGE=library/nginx:latest \
  -e WEBHOOK_URL=https://example.com/webhook \
  -e WEBHOOK_TOKEN=your-secret-token \
  -e CHECK_INTERVAL=300 \
  your-registry/docker-webhook-updater:latest

GitHub Container Registry Example

docker run -d \
  -e DOCKER_REPO_URL=ghcr.io \
  -e DOCKER_IMAGE=username/repo:latest \
  -e WEBHOOK_URL=https://example.com/webhook \
  -e WEBHOOK_TOKEN=your-secret-token \
  your-registry/docker-webhook-updater:latest

Docker Compose Example

version: "3.8"

services:
  webhook-updater:
    image: your-registry/docker-webhook-updater:latest
    environment:
      - DOCKER_REPO_URL=docker.io
      - DOCKER_IMAGE=library/nginx:latest
      - WEBHOOK_URL=https://example.com/webhook
      - WEBHOOK_TOKEN=your-secret-token
      - CHECK_INTERVAL=300
    restart: unless-stopped

How It Works

1. The service periodically checks the Docker registry for the specified image
2. It retrieves the SHA256 digest of the image manifest
3. Compares the current SHA with the previously stored SHA
4. If different, triggers the webhook with a POST request containing:

   {
     "event": "image_updated",
     "image": "username/image:latest",
     "repo_url": "docker.io"
   }
   

5. Updates the stored SHA only after successful webhook trigger

Webhook Request Format

When an image update is detected, the service sends a POST request to the webhook URL:

• Method: POST
• Headers:
  • Authorization: Bearer {WEBHOOK_TOKEN}
  • Content-Type: application/json
• Body:

  {
    "event": "image_updated",
    "image": "username/image:tag",
    "repo_url": "docker.io"
  }
  

Notes

• The SHA is stored in /app/sha.txt inside the container
• On first run, the SHA is stored without triggering the webhook
• If the webhook fails, the SHA is not updated, so it will retry on the next check
• For private Docker images, authentication may be required (not currently supported)
• The service runs continuously and checks at the specified interval

Building

docker build -t docker-webhook-updater:latest .