Skip to content
Hoody Documentation
Download Page (.md)

Real-Time Streaming

Section titled “Real-Time Streaming”

The Hoody notification server supports real-time streaming of notification updates via Server-Sent Events (SSE). This allows your application to receive push-style updates from the server as soon as they occur, without polling.

When to use streaming

Section titled “When to use streaming”

Use real-time streaming when you need your application to react to notification events the moment they are produced. Typical scenarios include:

  • Live dashboards — updating unread counts, activity feeds, or status indicators as notifications arrive.
  • In-app toasts and banners — surfacing a new message, mention, or system alert immediately.
  • Multi-device synchronization — keeping notification state consistent across browser tabs, mobile clients, and background services.
  • Event-driven automations — triggering workflows in response to specific notification types.

If your integration only needs notification history or periodic reconciliation, the standard REST endpoints for listing and fetching notifications are a better fit. Streaming is intended for low-latency, push-based consumption.

How it works

Section titled “How it works”

The streaming endpoint maintains a long-lived HTTP connection from the client to the Hoody notification server. Over that connection, the server emits structured SSE events whenever a notification relevant to the authenticated context is created, updated, or deleted. The client is responsible for handling reconnects, parsing the event stream, and dispatching events to your application logic.

Connection model

Section titled “Connection model”
  • The connection is established over HTTPS and authenticated using the same credentials as the REST API.
  • The server keeps the connection open and pushes events as they occur. If the connection drops, the client should reconnect and resume from the last received event identifier.
  • Heartbeat or comment frames are sent periodically to keep intermediaries from idling out the connection; clients should ignore unknown event types.

Event shape

Section titled “Event shape”

Each event delivered over the stream follows the SSE specification: an event name, one or more data lines containing a JSON payload, an optional id for resumption, and a blank line terminator. The data payload typically mirrors the notification object returned by the REST endpoints, so you can reuse existing parsing and rendering logic.

Client responsibilities

Section titled “Client responsibilities”

When consuming the stream, your client should:

  • Parse the event and data fields and route payloads to the appropriate handlers.
  • Track the most recent id value so reconnections can resume from the last known position.
  • Implement exponential backoff on reconnect, capped at a sensible interval.
  • Apply idempotency: the same event may be redelivered after a reconnect, so handlers should be safe to invoke more than once.

Operational considerations

Section titled “Operational considerations”
  • Streaming connections consume a server-side slot per active client. Open the stream only for sessions that need live updates, and close it when the user logs out or the application goes to the background.
  • Behind corporate proxies or load balancers, ensure idle timeouts are configured to exceed the server’s heartbeat interval, otherwise the connection will be terminated prematurely.
  • For high-volume consumers, prefer filtering on the client side after parsing rather than opening multiple parallel streams for the same user.

Next steps

Section titled “Next steps”