Webhooks

Trigger container watches and updates from external systems like CI/CD pipelines.

Overview

The webhook API lets external systems trigger container watches and updates. This is useful for CI/CD integration — after pushing a new image, your pipeline can tell drydock to check for updates immediately instead of waiting for the next scheduled watch cycle.

Configuration

Env var	Required	Description	Supported values	Default value when missing
`DD_SERVER_WEBHOOK_ENABLED`	⚪	Enable webhook endpoints	`true`, `false`	`false`
`DD_SERVER_WEBHOOK_TOKEN`	⚪	Shared Bearer token used by all webhook endpoints (fallback token)	Any string	—
`DD_SERVER_WEBHOOK_TOKENS_WATCHALL`	⚪	Endpoint-specific token for `POST /api/v1/webhook/watch`	Any string	—
`DD_SERVER_WEBHOOK_TOKENS_WATCH`	⚪	Endpoint-specific token for `POST /api/v1/webhook/watch/:containerName`	Any string	—
`DD_SERVER_WEBHOOK_TOKENS_UPDATE`	⚪	Endpoint-specific token for `POST /api/v1/webhook/update/:containerName`	Any string	—
`DD_SERVER_WEBHOOK_SECRET`	⚪	HMAC signing secret for verifying registry webhook signatures. Required when receiving push notifications from container registries.	Any string	—

Webhooks are disabled by default. Set DD_SERVER_WEBHOOK_ENABLED=true and provide at least one webhook token (DD_SERVER_WEBHOOK_TOKEN or any DD_SERVER_WEBHOOK_TOKENS_* value). Requests to endpoints without a configured token are rejected.

Endpoints

Method	Endpoint	Description
`POST`	`/api/v1/webhook/watch`	Trigger a watch cycle on all watchers
`POST`	`/api/v1/webhook/watch/:containerName`	Watch a specific container by name
`POST`	`/api/v1/webhook/update/:containerName`	Trigger an update on a specific container
`POST`	`/api/v1/webhooks/registry`	Receive signed registry push events and trigger targeted checks

Authentication

All webhook requests require a Bearer token in the Authorization header:

Authorization: Bearer your-token-here

Token selection rules:

If an endpoint-specific token (DD_SERVER_WEBHOOK_TOKENS_*) is set for that endpoint, it is required.
Otherwise, drydock falls back to DD_SERVER_WEBHOOK_TOKEN.

/api/v1/webhooks/registry uses HMAC signature validation (not Bearer token auth). Supported signature headers include x-registry-signature, x-hub-signature-256, x-quay-signature, x-harbor-signature, x-ms-signature, and x-drydock-signature.

Rate limiting

Webhook endpoints are rate-limited per client IP:

POST /api/v1/webhook/*: 30 requests per 15-minute window
POST /api/v1/webhooks/registry: 60 requests per 15-minute window

Per-container opt-out

Individual containers can be excluded from webhook API calls using the dd.webhook.enabled label. When set to false, the /api/v1/webhook/watch/:containerName and /api/v1/webhook/update/:containerName endpoints return 403 Forbidden for that container.

services:
  myapp:
    image: myapp:latest
    labels:
      - dd.watch=true
      - dd.webhook.enabled=false  # blocks webhook watch/update for this container

The dd.webhook.enabled label only affects per-container webhook endpoints. The global POST /api/v1/webhook/watch endpoint (which triggers all watchers) and POST /api/v1/webhooks/registry are not affected.

Containers without this label default to dd.webhook.enabled=true — webhooks are allowed unless explicitly disabled.

Audit logging

All webhook calls are recorded in the audit trail with action types webhook-watch, webhook-watch-container, and webhook-update, including success/error status and container details. A dd_webhook_total Prometheus counter tracks invocations by action type.

Examples

Watch all containers

curl -X POST https://drydock.example.com/api/v1/webhook/watch \
  -H "Authorization: Bearer your-token-here"

Watch a specific container

curl -X POST https://drydock.example.com/api/v1/webhook/watch/myapp \
  -H "Authorization: Bearer your-token-here"

Update a specific container

curl -X POST https://drydock.example.com/api/v1/webhook/update/myapp \
  -H "Authorization: Bearer your-token-here"

Registry push webhook (signed)

curl -X POST https://drydock.example.com/api/v1/webhooks/registry \
  -H "Content-Type: application/json" \
  -H "x-registry-signature: sha256=<hmac-of-raw-body>" \
  -d '{"events":[{"action":"push"}]}'

CI/CD integration

GitHub Actions

- name: Notify drydock
  run: |
    curl -X POST https://drydock.example.com/api/v1/webhook/watch/myapp \
      -H "Authorization: Bearer ${{ secrets.DRYDOCK_WEBHOOK_TOKEN }}"

GitLab CI

notify_drydock:
  stage: deploy
  script:
    - curl -X POST https://drydock.example.com/api/v1/webhook/watch/myapp \
      -H "Authorization: Bearer $DRYDOCK_WEBHOOK_TOKEN"

Docker Compose example

services:
  drydock:
    image: codeswhat/drydock
    environment:
      - DD_SERVER_WEBHOOK_ENABLED=true
      - DD_SERVER_WEBHOOK_TOKENS_WATCHALL=my-watchall-token
      - DD_SERVER_WEBHOOK_TOKENS_WATCH=my-watch-token
      - DD_SERVER_WEBHOOK_TOKENS_UPDATE=my-update-token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "3000:3000"

docker run -d \
  -e DD_SERVER_WEBHOOK_ENABLED=true \
  -e DD_SERVER_WEBHOOK_TOKENS_WATCHALL=my-watchall-token \
  -e DD_SERVER_WEBHOOK_TOKENS_WATCH=my-watch-token \
  -e DD_SERVER_WEBHOOK_TOKENS_UPDATE=my-update-token \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  codeswhat/drydock

Webhooks

On this page