Event Bus

The event bus provides topic-based pub/sub messaging across the platform, backed by NATS. Learn about topic routing, subscriptions, and event delivery.

The event bus is the platform's distributed messaging system. It routes events from producers to consumers using a topic-based pub/sub model, backed by NATS.

Topics

Events are routed through topics — hierarchical addresses that describe the event:

events.{orgId}.{source}.{resource}.{event}.{resourceId}[.{filterKey}.{filterValue}...]

Segment	Description	Example
`orgId`	Organization scope	`org_abc123`
`source`	The originating service	`conversations`, `flows`, `apps`
`resource`	The resource type	`conversation`, `flow`, `task`
`event`	What happened	`created`, `message_posted`, `completed`
`resourceId`	The specific resource	`conv_xyz`, `*` (wildcard)
`filterKey.filterValue`	Optional additional filters	`participant.part_789`

Topic examples

Topic	What it matches
`events.org_123.conversations.conversation.message_posted.*`	All messages in org_123
`events.org_123.flows.flow.run.*`	All flow runs in org_123
`events.*.apps.app.event_received.app_456`	Webhook events for app_456 across all orgs
`events.org_123.conversations.conversation.message_posted.*.participant.part_789`	Messages filtered by participant

Wildcards

The * wildcard matches any single segment. This enables flexible subscriptions:

Subscribe to all events of a type across all resources
Subscribe to all events for a specific resource regardless of event type
Subscribe across all organizations (for system-level handlers)

Publishing events

Services publish events by specifying the event name and payload:

Publish(context, "conversation.message_posted", Event{
    ResourceID: conversationId,
    Payload:    messageData,
})

The event bus constructs the full topic from the event context (organization, source service, resource type) and routes it to matching subscribers.

Subscribing to events

Subscribers register handlers for specific topic patterns:

Subscribe(orgId, "conversation.message_posted", handler, filters, localOnly)

Parameters:

Parameter	Description
`orgId`	Organization to scope the subscription (or `*` for all)
`eventName`	The event pattern to match
`handler`	The function to call when a matching event arrives
`filters`	Optional additional filter criteria
`localOnly`	If `true`, only matches events on the same instance (used for instance-affine handlers like conversation flow triggers)

Event subscriptions configured through the API (for example, webhook event subscriptions for apps) are persisted in the database. When the platform restarts, these subscriptions are automatically restored.

Local-only subscriptions

Some handlers need to run only on the instance that owns the relevant state. For example, flow engine handlers that manage active flow runs subscribe with localOnly: true to ensure messages for a running flow are handled by the instance that owns the flow execution.

Event delivery

Events are dispatched asynchronously through a bounded worker pool:

Events are placed in a queue
A pool of workers processes events concurrently
Each worker evaluates the event against registered handlers and dispatches matches

This architecture ensures that event processing doesn't block the publishing service and handles bursts gracefully.

Persistence

The event bus supports two persistence modes:

Ephemeral — events are delivered to current subscribers only. If no subscriber is listening, the event is lost.
Persistent (via NATS JetStream) — events are stored and can be replayed. Used for critical events like webhook deliveries that must not be lost.

Event System overview — the broader event architecture
Notifications — event-driven user notifications
Event Channels — external event ingestion
Real-time Messaging — WebSocket delivery to clients