Skip to content
Drydock
ConfigurationWebhooks

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 varRequiredDescriptionSupported valuesDefault value when missing
DD_SERVER_WEBHOOK_ENABLED⚪Enable webhook endpointstrue, falsefalse
DD_SERVER_WEBHOOK_TOKEN⚪Shared Bearer token used as the fallback for the three /api/v1/webhook/* action endpointsAny string—
DD_SERVER_WEBHOOK_TOKENS_WATCHALL⚪Endpoint-specific token for POST /api/v1/webhook/watch. If any endpoint-specific token is set, all three endpoint-specific tokens must be set.Any string—
DD_SERVER_WEBHOOK_TOKENS_WATCH⚪Endpoint-specific token for POST /api/v1/webhook/watch/:containerName. If any endpoint-specific token is set, all three endpoint-specific tokens must be set.Any string—
DD_SERVER_WEBHOOK_TOKENS_UPDATE⚪Endpoint-specific token for POST /api/v1/webhook/update/:containerName. If any endpoint-specific token is set, all three endpoint-specific tokens must be set.Any string—
DD_SERVER_WEBHOOK_SECRET⚪HMAC signing secret for verifying registry webhook signatures (the hmac mode).Any string—
DD_SERVER_WEBHOOK_STATICSECRET⚪Static secret for registries that cannot sign webhooks. Used by the path, query and bearer modes of every provider that doesn't set its own. Supports DD_SERVER_WEBHOOK_STATICSECRET__FILE.String of 16 or more characters—
DD_SERVER_WEBHOOK_REGISTRIES_<PROVIDER>_MODES⚪Comma-separated auth modes accepted for one provider. <PROVIDER> is DOCKERHUB, GHCR, HARBOR, QUAY, ACR or ECR.hmac, path, query, bearerhmac
DD_SERVER_WEBHOOK_REGISTRIES_<PROVIDER>_SECRET⚪Static secret for that provider only, overriding DD_SERVER_WEBHOOK_STATICSECRET. Supports __FILE.String of 16 or more characters—
Webhooks are disabled by default. Set DD_SERVER_WEBHOOK_ENABLED=true. The three /api/v1/webhook/* action endpoints require either DD_SERVER_WEBHOOK_TOKEN or all three endpoint-specific tokens; partial endpoint-token sets are rejected at startup. /api/v1/webhooks/registry separately requires DD_SERVER_WEBHOOK_SECRET (HMAC) or a static secret for each provider that uses one. Configure both token auth and the secret when using both endpoint groups.

Endpoints

MethodEndpointDescription
POST/api/v1/webhook/watchTrigger a watch cycle on all watchers
POST/api/v1/webhook/watch/:containerNameWatch a specific container by name
POST/api/v1/webhook/update/:containerNameTrigger an update on a specific container
POST/api/v1/webhooks/registryReceive HMAC-signed registry push events and trigger targeted checks
POST/api/v1/webhooks/registry/:providerRegistry push events authenticated by Authorization: Bearer, ?secret= or HMAC, per provider config
POST/api/v1/webhooks/registry/:provider/:secretRegistry push events authenticated by a secret in the URL path

POST /api/v1/webhook/watch runs through the same single-flight scan orchestration as the scheduled cron scan, rather than starting an independent scan of its own: a call that lands while a scan is already running for a watcher is folded into that scan's follow-up instead, and the JSON response's result.coalesced field is true when that happened for at least one watcher.

Duplicate container names

The per-container webhook endpoints resolve :containerName by name. In multi-agent deployments, the same container name can exist on multiple agents or watchers. When a name is ambiguous, drydock returns 409 Conflict and includes the matching agent/watcher pairs in the error message.

Add query parameters to disambiguate:

  • ?agent=<agentName> targets containers owned by a remote agent.
  • ?agent=__local__ targets controller-local containers without an agent.
  • ?watcher=<watcherName> narrows the match to a watcher.
curl -X POST "https://drydock.example.com/api/v1/webhook/update/myapp?agent=edge-1&watcher=local" \
  -H "Authorization: Bearer your-token-here"

Authentication

Action webhooks: Bearer tokens

/api/v1/webhook/* requests require a Bearer token in the Authorization header:

Authorization: Bearer your-token-here

Token selection rules:

  • Endpoint-specific tokens are all-or-none: if any DD_SERVER_WEBHOOK_TOKENS_* value is set, WATCHALL, WATCH, and UPDATE must all be configured.
  • If endpoint-specific tokens are configured, the matching token for that endpoint is required.
  • Otherwise, drydock falls back to DD_SERVER_WEBHOOK_TOKEN.

Registry webhooks

Registry webhooks accept four auth modes, chosen per provider with DD_SERVER_WEBHOOK_REGISTRIES_<PROVIDER>_MODES:

ModeCredentialEndpoint
hmac (default)HMAC-SHA256 of the raw body in a signature header/api/v1/webhooks/registry or /api/v1/webhooks/registry/:provider
pathStatic secret as the last URL segment/api/v1/webhooks/registry/:provider/:secret
queryStatic secret in ?secret=/api/v1/webhooks/registry/:provider?secret=...
bearerStatic secret in Authorization: Bearer <secret>/api/v1/webhooks/registry/:provider

:provider is dockerhub, ghcr, harbor, quay, acr or ecr. A provider that sets no modes accepts hmac only, exactly as before. A credential for a mode the provider doesn't allow is treated as if it weren't sent. The payload must also parse as that provider's format, or the request gets a 400.

POST /api/v1/webhooks/registry does not use Bearer authentication and stays HMAC-only. Bearer applies only to /api/v1/webhooks/registry/:provider when that provider allows the bearer mode. For HMAC, configure DD_SERVER_WEBHOOK_SECRET=your-registry-webhook-secret, then sign the exact raw request body with HMAC-SHA256. Signature values may be the 64-character hex digest or use the sha256= prefix, and the supported headers are x-registry-signature, x-hub-signature-256, x-quay-signature, x-harbor-signature, x-ms-signature and x-drydock-signature.

payload='{"repository":{"repo_name":"library/nginx"},"push_data":{"tag":"latest"}}'
signature="$(printf '%s' "$payload" | openssl dgst -sha256 -hmac "$DD_SERVER_WEBHOOK_SECRET" | awk '{print $NF}')"

curl -X POST https://drydock.example.com/api/v1/webhooks/registry \
  -H "Content-Type: application/json" \
  -H "x-drydock-signature: sha256=${signature}" \
  --data-binary "$payload"

Static secrets are compared in constant time. They are never logged: failed attempts log the provider and a path with the secret segment masked, and the query string is dropped. Failed attempts also count against a tighter rate limit (20 per 15 minutes per client IP) than successful ones.

A secret in the URL (path or query) is stored in the registry's own webhook configuration and can show up in its delivery logs, and in any proxy or load balancer access log in front of Drydock. Use a dedicated secret for registry webhooks that you can rotate, never one shared with another system, and prefer bearer where the registry supports custom headers.

Configure each registry

Set a secret first. It must be at least 16 characters:

DD_SERVER_WEBHOOK_ENABLED=true
DD_SERVER_WEBHOOK_STATICSECRET__FILE=/run/secrets/registry_webhook_secret
RegistryWhyModeWhere the secret goes
Docker HubCan't sign requests or set headerspath or queryWebhook URL
QuayCan't sign requests or set headerspath or queryNotification URL
HarborCustom auth header, no HMACbearerWebhook "Auth Header"
Azure Container RegistryCustom headers, no HMACbearerWebhook custom header
GHCR (GitHub)Signs with X-Hub-Signature-256hmacGitHub webhook secret
Amazon ECREventBridge relayhmacAs before

Docker Hub. Repository, then Webhooks. Set the webhook URL to https://drydock.example.com/api/v1/webhooks/registry/dockerhub/<secret>.

DD_SERVER_WEBHOOK_REGISTRIES_DOCKERHUB_MODES=path

Quay. Repository, then Settings, then Create Notification, event "Push to Repository", method "Webhook POST". Set the URL to https://drydock.example.com/api/v1/webhooks/registry/quay/<secret>.

DD_SERVER_WEBHOOK_REGISTRIES_QUAY_MODES=path

Harbor. Project, then Webhooks, then New Webhook, event "Artifact pushed". Endpoint URL https://drydock.example.com/api/v1/webhooks/registry/harbor, and set "Auth Header" to Bearer <secret>.

DD_SERVER_WEBHOOK_REGISTRIES_HARBOR_MODES=bearer

Azure Container Registry. Registry, then Webhooks, then Add. Service URI https://drydock.example.com/api/v1/webhooks/registry/acr, action "push", and add the custom header Authorization with the value Bearer <secret>.

DD_SERVER_WEBHOOK_REGISTRIES_ACR_MODES=bearer

GHCR. Unchanged. Create a repository or organization webhook, set the payload URL to https://drydock.example.com/api/v1/webhooks/registry, content type application/json, and use DD_SERVER_WEBHOOK_SECRET as the webhook secret.

Amazon ECR. Unchanged. Forward the EventBridge event with an HMAC signature using DD_SERVER_WEBHOOK_SECRET, as described above.

To give one provider its own secret instead of the shared one, set DD_SERVER_WEBHOOK_REGISTRIES_<PROVIDER>_SECRET. To allow more than one mode, list them: DD_SERVER_WEBHOOK_REGISTRIES_HARBOR_MODES=bearer,hmac.

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"

Successful update requests return 202 Accepted with the queued operation id:

{
  "message": "Update accepted for container myapp",
  "operationId": "018f...",
  "result": {
    "container": "myapp"
  }
}

Registry push webhook (HMAC)

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"}]}'

Registry push webhook (static secret)

curl -X POST https://drydock.example.com/api/v1/webhooks/registry/dockerhub/$REGISTRY_WEBHOOK_SECRET \
  -H "Content-Type: application/json" \
  -d '{"repository":{"repo_name":"library/nginx"},"push_data":{"tag":"latest"}}'

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:1.9.0-rc.1
    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"