Event System

The platform's distributed event system enables real-time communication between services, external event ingestion, and notification delivery through a topic-based pub/sub architecture.

The event system is the communication backbone of the platform. It enables services to publish and subscribe to events, routes external events from integrations, and powers real-time notifications.

Architecture

The event system is built on a pub/sub model backed by NATS:

Services publish events
  → Event bus (NATS)
    → Topic-based routing
      → Subscribers receive matching events
        → Flows, notifications, WebSockets, handlers

Every platform service publishes events when state changes occur. Other services, flow triggers, and connected clients subscribe to the events they care about.

Event structure

Each event contains:

Field	Description
id	Unique event identifier
organizationId	The organization context
source	The service that produced the event (for example, `conversations`, `flows`)
resource	The resource type (for example, `conversation`, `flow`, `task`)
resourceId	The specific resource instance
eventName	What happened (for example, `created`, `updated`, `message_posted`)
timestamp	When the event occurred
payload	The event data (JSON)
metadata	Additional context (filters, tags)

Internal events

Platform services publish events for all significant state changes:

Service	Example events
Conversations	`conversation.created`, `conversation.message_posted`, `conversation.message_stream`
Flows	`flow.created`, `flow.updated`, `flow.run`
Tasks	`task.created`, `task.completed`, `task.failed`
Apps	`app.installed`, `app.event_received`
Collections	`record.created`, `record.updated`, `record.deleted`

These events drive the platform's reactive behavior — flows start in response to events, notifications are sent, and connected clients receive updates.

External events

Events from external systems enter the platform through event channels defined in integrations. See Event Channels for details on webhook, SSE, and polling channels.

External events are published to the event bus with a standard topic format, making them available to the same subscribers as internal events.

In this section

Event Bus — topic routing, subscriptions, and the NATS-backed pub/sub system
Notifications — event-driven user notifications with multi-channel delivery