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.

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

Scan Events

• Started
• Completed
• Failed

Update Events

• Started
• Completed
• Failed

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}}

HTTP Status Codes