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_FEATURE_WEBHOOK`	⚪	Enable webhook endpoints	`true`, `false`	`true`
`DD_SERVER_WEBHOOK_TOKEN`	🔴	Bearer token for webhook authentication	Any string	—

Webhooks require a DD_SERVER_WEBHOOK_TOKEN to be set. Without it, webhook endpoints will reject all requests.

Endpoints

Method	Endpoint	Description
`POST`	`/api/webhook/watch`	Trigger a watch cycle on all watchers
`POST`	`/api/webhook/watch/:containerName`	Watch a specific container by name
`POST`	`/api/webhook/update/:containerName`	Trigger an update on a specific container

Authentication

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

Authorization: Bearer your-token-here

Rate limiting

Webhook endpoints are rate-limited to 30 requests per 15-minute window per client IP.

Examples

Watch all containers

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

Watch a specific container

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

Update a specific container

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

CI/CD integration

GitHub Actions

- name: Notify drydock
  run: |
    curl -X POST https://drydock.example.com/api/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/webhook/watch/myapp
        -H "Authorization: Bearer $DRYDOCK_WEBHOOK_TOKEN"

Docker Compose example

services:
  drydock:
    image: codeswhat/drydock
    environment:
      - DD_SERVER_WEBHOOK_TOKEN=my-secret-token
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    ports:
      - "3000:3000"

docker run -d \
  -e DD_SERVER_WEBHOOK_TOKEN=my-secret-token \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -p 3000:3000 \
  codeswhat/drydock

Webhooks

On this page