Subscribe

Subscribing to a stream in Litebase means listening for new events as they’re published. You can use this to trigger background jobs, update UIs, sync downstream systems, or react to any change across your stack — instantly and reliably.

This guide walks you through how to subscribe to a stream, what event payloads look like, and how to handle real-time delivery in your app or service.

1. Choose a stream to listen to

Each stream is a logical channel. Use stream names to scope your listeners to just the events you care about.

Examples:

• user.signup
• payment.success
• job.failed

You can subscribe to one stream or multiple, depending on your use case. All events are delivered in the order they were committed.

2. Pick a transport

Litebase supports multiple delivery options:

• Server-Sent Events (SSE) – Simple and reliable for browser-based or backend listeners
• WebSocket – Bi-directional channel for more interactive or stateful apps
• Webhook (coming soon) – Push events to external services over HTTP

Choose the one that fits your environment. All transports support the same event format.

3. Connect to the stream

To subscribe over SSE, send an HTTP GET request to the stream’s endpoint:

curl -N https://api.litebase.io/v1/streams/user.signup/subscribe \
  -H "Authorization: Bearer $LITEBASE_API_KEY" \
  -H "Accept: text/event-stream"

As events are published, you’ll receive lines like this:

event: message
data: {"time":"2025-04-05T12:00:00Z","tx":"tx_7a29d1a3","stream":"user.signup","data":{"user_id":"abc123","email":"[email protected]"}}

You can parse the data: line as JSON and act accordingly.

4. Handle event delivery

Every event includes:

• stream: the stream name
• time: when the event was committed
• tx: the transaction ID
• data: your custom event payload

Example parsed event:

{
  "time": "2025-04-05T12:00:00Z",
  "tx": "tx_7a29d1a3",
  "stream": "user.signup",
  "data": {
    "user_id": "abc123",
    "email": "[email protected]"
  }
}

These events are immutable and delivered in commit order. You can safely trigger async jobs, update UI state, or log them for observability.

5. (Optional) Resume from a known point

If your connection drops or you want to backfill missed events, you can resume by providing a since parameter:

curl -N "https://api.litebase.io/v1/streams/user.signup/subscribe?since=tx_7a29d1a3" \
  -H "Authorization: Bearer $LITEBASE_API_KEY"

This will deliver all events after the given transaction ID — allowing you to catch up and avoid gaps.