Exception Events Gateway Contract (draft v0.1)

This contract defines the Server-Sent Events (SSE) stream that the Stella Ops Web gateway exposes for exception workflow events (exception.*). It is consumed by Console activity feeds and by Notify integrations that surface exception changes to operators.

Security / headers

• Authorization: Bearer <token> (or DPoP where configured).
• X-StellaOps-TenantId: <tenantId> (required; see tenant-auth).
• X-StellaOps-Project: <projectId> (optional; legacy alias X-Stella-Project is accepted only when the gateway is started with EnableLegacyHeaders=true).
• Scopes: exceptions:read.

Endpoint

• GET /exceptions/events — Server-Sent Events (SSE) stream.
  • Query params (all optional): tenant, traceId, projectId.
  • Response: text/event-stream.

Event types

• exception.created
• exception.updated
• exception.status_changed
• exception.deleted

Rate limits (proposal)

• Maximum one active SSE connection per browser session.
• Heartbeat every 30s; the server closes idle connections after 60s without reads.
• When rate limited, the gateway returns 429 with a Retry-After header.

Notify integration

Where configured, the gateway forwards these events to Notify:

• exception.status_changed → notify.event, with severity derived from the exception severity and status.
• All events include traceId for audit correlation.

Samples

• samples/exception-events.ndjson