Event

Introduction

This specification defines how a Web Function package can signal that it supports real-time, asynchronous streams of data using Server-Sent Events (SSE), and how clients can use this feature to subscribe to these streams.

Global stream

A package may include an event_source_url at the top level. This serves as a persistent, global entry point for an SSE connection, typically used for system-wide notifications or broad updates.

Event source flag

An endpoint may include the event_source flag. This indicates that the endpoint, when called, will return a string containing a URL. This URL is then used by the client to initialize a connection via the browser's EventSource API.

Receiving events

Clients receive events by subscribing to an event source URL. Each event sent over the stream MUST be a JSON object with a mandatory key named event, whose value is the name of the event. The remaining keys carry the data relevant to that event.

When the stream belongs to a package, the value of event MUST match the name of an entry in the package's events array, and the object's remaining keys MUST correspond to that event's declared attributes. See the package specification for the event definition.

const eventSource = new EventSource(eventSourceUrl);

eventSource.onmessage = (event) => {
  // Each event message is a JSON string with an "event" property
  const data = JSON.parse(event.data);
  console.log("Received event:", data.event, data);
};

SSE framing

Events MUST be delivered as the default SSE message type, so that the browser's onmessage handler receives them. The application-level event name is carried in the JSON event field of the payload, not in the SSE event: line. The SSE id: and retry: fields, and the reconnection behavior they enable, are out of scope for this specification.

Authentication

The bearer token mechanism defined in the authentication specification does not apply to event streams, because browser EventSource clients cannot set custom headers such as Authorization. Instead, any URL used for an event stream (whether from the package or an endpoint) MAY carry the necessary authentication tokens or session identifiers in the query string or path.

Because such credentials appear in the URL, they can leak through server logs, browser history, and Referer headers. Implementers SHOULD prefer short-lived, single-purpose tokens for event stream URLs and SHOULD avoid reusing long-lived bearer tokens there.