Document Utilities

Webhooks & Server-Sent Events (SSE)

Real-time AI UX feels dramatically better when output is streamed token-by-token instead of delivered as one large block. Server-Sent Events (SSE) provide a lightweight one-way stream from server to browser over standard HTTP, making them ideal for incremental response rendering.

How SSE Works

  • Client opens a persistent connection to an SSE endpoint.
  • Server emits lines prefixed by data: as tokens become available.
  • Browser processes each event instantly and updates UI progressively.
  • Connection closes after completion or error.

Streaming Lifecycle

Open Stream
→
Receive Tokens
→
Render Incrementally
→
Close on Done

VS Code Style JavaScript EventSource Example

// Connect to SSE stream for token-by-token generation
const output = document.getElementById("stream-output");
const source = new EventSource("/v1/events/stream?chat_id=abc123");

source.onmessage = (event) => {
  const payload = JSON.parse(event.data);
  if (payload.type === "token") {
    output.textContent += payload.value;
  }
  if (payload.type === "done") {
    source.close();
  }
};

source.onerror = () => {
  console.error("SSE stream interrupted");
  source.close();
};

Where Webhooks Fit

Webhooks are server-to-server push notifications useful for asynchronous lifecycle events: completed generations, moderation flags, usage threshold triggers, and training queue updates. Unlike SSE (browser stream), webhooks target your backend endpoints for durable workflow automation.

Operational Best Practices

  • Always send a final terminal event (for example done) to close UI state cleanly.
  • Use retry/backoff logic when SSE disconnects under unstable networks.
  • Sign webhook payloads and verify signatures before processing.
  • Store event IDs to make webhook processing idempotent.
Architectural takeaway: SSE maximizes perceived speed for end users, while webhooks maximize reliability for backend automation.