Watchtower HTTP API Mode — Trigger Updates On Demand

Why Trigger Updates On Demand?

Watchtower's default behavior is to poll on an interval — every 24 hours unless you change it. That's fine for "eventually current," but if your CI pipeline just pushed a new image and you want it live now, waiting for the next poll is annoying. HTTP API mode adds a webhook-style endpoint you can call right after a build finishes, so the deploy step becomes part of your pipeline instead of a waiting game.

Enabling HTTP API Mode

Two things are required: the --http-api-update flag (or its equivalent) and an API token. Watchtower refuses to start the HTTP API without a token configured — there's no way to run it unauthenticated.

services:
  watchtower:
    image: containrrr/watchtower
    restart: unless-stopped
    ports:
      - "8080:8080"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - WATCHTOWER_HTTP_API_UPDATE=true
      - WATCHTOWER_HTTP_API_TOKEN=change-this-to-a-long-random-string

Pick the token the same way you'd pick any API secret — long, random, and not reused from somewhere else. Anyone with this token can trigger updates on every container Watchtower manages on this host.

Calling the Endpoint

The endpoint is /v1/update on whatever port you exposed (8080 by default). Every request needs the token in an Authorization: Bearer header:

curl -H "Authorization: Bearer change-this-to-a-long-random-string" \
  http://your-host:8080/v1/update

This triggers an update check for all containers Watchtower is monitoring on that instance — it's not scoped to a single container by default. If you need to limit which containers get checked, combine this with label-based opt-in (WATCHTOWER_LABEL_ENABLE=true) so only intentionally-labeled containers are affected.

Polling vs. On-Demand — Not Automatically Both

Turning on HTTP API mode switches Watchtower to on-demand-only by default — it stops polling on a schedule. If you want the periodic poll and the on-demand endpoint running side by side, you need to explicitly keep periodic polling active as well (check your image version's flag reference, since flag names have shifted slightly between the archived containrrr release and the newer forks — see our environment variables reference for the full list on the image you're running).

Example: Calling It From a CI Pipeline

# After pushing a new image tag in your CI job:
curl -f -H "Authorization: Bearer $WATCHTOWER_TOKEN" \
  https://watchtower.internal.example.com:8080/v1/update

Put the token in your CI system's secret store, not in the pipeline file itself. If the Watchtower host is reachable from the public internet, put this endpoint behind a reverse proxy with its own access controls (IP allowlist, mTLS, or a proxy-level auth layer) rather than relying on the bearer token alone as your only line of defense.