Skip to content

Events

Overview

The /v1/events endpoint streams Watchtower operational events via Server-Sent Events (SSE). Include events in http-api-endpoints to enable this endpoint.

Not usable via Swagger UI Try it out

Swagger UI will show a permanent Loading spinner on this endpoint even after successful authentication. The UI uses fetch and expects a finished response body; SSE is an open stream. Use curl -N or browser EventSource as shown below (see also Swagger UI).

Authentication

The events endpoint requires authentication via the HTTP API Events Token configuration option.

This token can be provided in two formats:

  • Header-based auth — For programmatic clients using curl, fetch, etc.:
curl -N -H "Authorization: Bearer my-events-token" "http://localhost:8080/v1/events"
  • Query-parameter auth — For browser EventSource API, which cannot send custom headers:
const eventSource = new EventSource('http://localhost:8080/v1/events?access_token=my-events-token');

eventSource.addEventListener('scan_started', (e) => {
    console.log('Scan started:', JSON.parse(e.data));
});

eventSource.addEventListener('scan_completed', (e) => {
    console.log('Scan completed:', JSON.parse(e.data));
});
curl -N "http://localhost:8080/v1/events?access_token=my-events-token"

The events endpoint uses a separate token from the main API token to limit blast radius, since query parameters may appear in access logs, browser history, and proxy logs.

Supported Events

Each event is sent under its type as the SSE event name:

Event Sent data fields
scan_started Before an update session or a check begins The update policy as booleans: cleanup, no_restart, monitor_only, lifecycle_hooks, rolling_restart, label_precedence, no_pull, run_once, use_compose_depends_on, skip_self_update, ephemeral_self_update, revive_stopped
scan_completed After an update session or a check ends without an error scanned, updated, failed, skipped
scan_failed When an update session or a check ends with an error error
image_cleanup After an update session removes old images images, each with image_id, image_name, container_id and container_name

Note

Update sessions are scheduled runs and /v1/update requests. Checks are /v1/check requests. A check updates nothing, so it never sends image_cleanup, and its scan_completed reports updated as 0.

Event Format

Each event is a Server-Sent Event with an event type and JSON data payload:

event: scan_completed
data: {"type":"scan_completed","timestamp":"2025-01-20T11:30:45Z","data":{"scanned":8,"updated":0,"failed":0,"skipped":0}}

HTTP Status Codes

Status Code Description
200 Event stream established
401 Invalid or missing authentication token
403 Origin not allowed