Publish

Publishing an event in Litebase means appending a new, immutable entry to a stream. You can use it to capture anything that happens in your system — a user signup, a payment confirmation, a state transition — and make that event available to other parts of your stack in real time.

This guide walks you through how to publish events, what to include in them, and how to think about streams as part of your architecture.

1. Choose a stream name

Streams are like topics — each one is a logical channel that groups related events. Stream names are flat strings and typically follow a domain-action pattern:

• user.signup
• order.shipped
• model.predicted
• job.started

Pick a name that describes what happened, not what will happen. Events are facts, not instructions.

2. Structure your data

The event body should include a data object — this is your payload. It can be any valid JSON, and should include just enough information for downstream consumers to act.

Example:

{
  "data": {
    "user_id": "abc123",
    "email": "[email protected]"
  }
}

Avoid large blobs or nested schemas unless absolutely necessary — remember that every event is immutable and stored permanently.

3. Send the event

To publish the event, send an HTTP POST request to the stream’s endpoint:

curl -X POST https://api.litebase.io/v1/streams/user.signup \
  -H "Authorization: Bearer $LITEBASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "data": {
          "user_id": "abc123",
          "email": "[email protected]"
        }
      }'

If successful, you'll receive a response that includes:

• The stream name
• A timestamp (time)
• A transaction ID (tx)

These metadata fields are assigned by Litebase and can be used later for correlation or replay.

4. Connect with subscribers

Once the event is published:

• Any active subscribers to the stream will receive the event in real time
• The event will be stored durably and can be replayed later from any point in time

This is where streams shine: you don’t need to know who’s listening — your system stays decoupled and reactive.

5. (Optional) Use with writes

You can also publish events as part of a larger transaction that includes storage writes. For example:

• Write a key: user:abc123 → { ... }
• Emit an event: user.signup → { user_id: abc123 }
• Commit both together under the same tx

This gives you strong consistency between data and event timelines — no race conditions, no guesswork.