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.