Custom Event Types

Details

The event: field in an SSE stream sets the event type for the next dispatched event. When the blank-line terminator is reached, a MessageEvent is created with the type property set to the event: value.

Default behavior: if no event: field is present, type is 'message'. If event: is empty string (''), type is also 'message'.

Use cases for custom event types: 1. Multiplexing – send 'price', 'news', 'alert' events on the same connection 2. Protocol versioning – 'v2.update' vs 'v1.update' 3. LLM streaming – 'content_block_delta', 'message_stop' (Anthropic Claude uses this) 4. Progress events – 'progress', 'complete', 'error'

The three built-in event names (message, open, error) cannot be used as custom types without conflicting with the browser's built-in handlers. Use onmessage for 'message' events, not addEventListener.

Multiple event types on one connection: the browser processes each event independently based on its type. You can have multiple addEventListener calls on a single EventSource for different types.

Examples

# Server sends named events:
event: price
data: {"symbol": "BTC", "price": 67432.10}

event: news
data: {"headline": "Bitcoin ETF approved"}

event: alert
data: {"severity": "high", "message": "Threshold exceeded"}

# Each blank line dispatches one event

const source = new EventSource('/market-stream');

source.addEventListener('price', (e) => {
  const tick = JSON.parse(e.data);
  updateChart(tick.symbol, tick.price);
});

source.addEventListener('news', (e) => {
  showBanner(JSON.parse(e.data).headline);
});

source.addEventListener('alert', (e) => {
  triggerAlert(JSON.parse(e.data));
});

# Anthropic API uses named SSE events:
event: message_start
data: {"type":"message_start","message":{...}}

event: content_block_delta
data: {"type":"content_block_delta","delta":{"text":"Hello"}}

event: message_stop
data: {"type":"message_stop"}

Gotchas