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 may contain additional data relevant to that event.

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

Authentication

Since browser EventSource clients do not support custom headers, any URL used for an event stream (whether from the package or an endpoint) should include necessary authentication tokens or session identifiers in the query string or path.