Core Concepts

Before diving into the API reference or service guides, it's important to understand the three foundational building blocks of the Realtime Platform and how they relate to each other.

A Topic is a named channel that events are published to. Subscribers (WebSocket clients, webhooks, SDK listeners) listen on topics to receive events. Topics are the central fan-out point for all event delivery in the platform.

session.status
order.updated
chat.room.message
proctor.session.started

Topics use dot-separated, lowercase names following a domain-driven convention. Every event in the system — regardless of how it was produced — is published to a topic.

Info

Topics can receive events from any source: Database CDC mappings, the Sync service, the Socket gateway, or direct SDK publishes. A topic doesn't care where the event came from — it just routes it to all interested subscribers.

Schemas — The Payload Contract (Optional)

A Schema is a versioned JSON Schema definition attached to a specific topic. It defines the expected shape of event payloads published to that topic.

Each topic can have multiple schema versions (1, 2, 3, ...).
The topic's activeSchemaVersion field points to the currently enforced version.
When a new event is published, the payload is validated against the active schema before delivery.
Backward compatibility mode ensures new schema versions don't break existing consumers.

Warning

Schemas are optional. A topic works perfectly fine without any schema — events are delivered with unvalidated, free-form payloads. Add a schema when you want to enforce a contract between producers and consumers.

Mappings — The CDC Bridge

A Mapping (also called a Domain Mapping) defines how a database table change — captured via Change Data Capture (CDC) — is transformed into an event and routed to a topic. A mapping specifies:

Which table to watch
Which operations to capture (insert, update, delete)
Which columns must change to trigger the event
What filter conditions to apply before routing
How to project row columns into the event payload
Which topic to publish the resulting event to

Info

Mappings are only relevant for the Database CDC pipeline. If you're publishing events from application code (via the SDK or Socket gateway), you don't need mappings at all.

How They Relate

┌──────────────┐       N:1        ┌─────────┐       1:N        ┌──────────────┐
│   Mapping    │ ──────────────── │  Topic   │ ──────────────── │   Schema     │
│ (CDC table → │   publishes to   │ (routing │   validates via  │ (versioned   │
│  event xform)│                  │  channel)│                  │  JSON Schema)│
└──────────────┘                  └─────────┘                  └──────────────┘

Relationship	Cardinality	Required?
Topic → Schemas	1 topic has 0..N schema versions	No — schemas are optional
Topic → Mappings	1 topic can be targeted by 0..N mappings	No — topics work without CDC
Mapping → Topic	Each mapping targets exactly 1 topic	Yes — `topic` is required on every mapping
Mapping → Schema	No direct link — the schema belongs to the topic, not the mapping	N/A

Key Takeaways

Topics are the center of everything. They are the single fan-out point that connects producers to consumers.
Schemas are optional and belong to topics, not to mappings. They validate payloads before delivery.
Mappings are optional and only used for CDC. They transform database row changes into topic events.
In the simplest case (one table, one topic, one schema), the relationship looks 1:1:1, but the design supports much more complex topologies.

The Topic Fan-Out Model

The topic is the single delivery point for all event types. Regardless of how an event enters the platform, it lands on a topic and fans out to all interested subscribers.

Event Sources (Producers)

Events can enter a topic from four different sources:

  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐
  │  CDC Mapping     │  │  Sync Service   │  │  Socket Gateway │  │  SDK publish()  │
  │  (DB row change  │  │  (document      │  │  (client sends  │  │  (app code      │
  │   → topic event) │  │   mutation)     │  │   message)      │  │   publishes)    │
  └────────┬─────────┘  └────────┬────────┘  └────────┬────────┘  └────────┬────────┘
           │                     │                     │                     │
           └─────────────────────┴──────────┬──────────┴─────────────────────┘
                                            │
                                            ▼
                                    ┌───────────────┐
                                    │     Topic     │
                                    │  (fan-out     │
                                    │   point)      │
                                    └───────┬───────┘
                                            │
                          ┌─────────────────┼─────────────────┐
                          │                 │                 │
                          ▼                 ▼                 ▼
                  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐
                  │  WebSocket   │  │  Webhook     │  │  SDK Event   │
                  │  Subscribers │  │  Endpoints   │  │  Listeners   │
                  └──────────────┘  └──────────────┘  └──────────────┘

Source	How it enters	Example
CDC Mapping	Database row change is transformed by a mapping and published to the mapping's target topic	`sessions` table update → `session.status` topic
Sync Service	Document create/update/delete publishes to `sync.{service}.{operation}`	Document merge → `sync.notes.updated` topic
Socket Gateway	Client publishes a message to a topic via Socket.IO or WebSocket	Chat message → `chat.room.message` topic
SDK `publish()`	Application code publishes an event directly to a topic	Background job → `report.generated` topic

Event Consumers (Subscribers)

When an event lands on a topic, it is delivered to all registered subscribers:

Consumer	How it subscribes	Delivery method
WebSocket clients	`subscribe({ topic: 'session.status' })` via Socket.IO or plain WebSocket	Real-time push over the open connection
Webhook endpoints	Registered via API/Admin UI with matching event types for the topic	HTTP POST with HMAC-SHA256 signature
SDK event listeners	`realtime.on('event:session.status', handler)`	Callback invoked with the event payload

Tip

To fire a webhook when something happens, you don't configure the webhook on a table or a mapping — you register the webhook endpoint against a topic. Any event that lands on that topic (from any source) will be delivered to matching webhook endpoints.

Schema Validation in the Flow

Schemas act as a gate between the producer and the fan-out. When a topic has an active schema version, the event payload is validated before it is delivered to subscribers:

Event from any source
        │
        ▼
   ┌──────────┐     ❌ Rejected
   │  Schema  │────────────────▶ (validation error)
   │ Validate │
   └────┬─────┘
        │ ✅ Valid
        ▼
   ┌──────────┐
   │  Topic   │
   │  Fan-out │
   └──────────┘
        │
   Delivered to all subscribers

If the topic has no schema (or activeSchemaVersion is 0), the validation step is skipped and events pass through freely.

Common Patterns

Pattern 1: Simple CDC → Webhook

Stream a database table change to an external HTTP endpoint.

Create a topic

Create a topic like session.status in Registry → Topics.

(Optional) Register a schema

Create a mapping

In Registry → Mappings, create a mapping from the sessions table to the session.status topic. Define which operations trigger it, which columns to watch, and how to build the payload.

Register a webhook

In Webhooks → Endpoints, create a webhook endpoint subscribed to the session.status topic. The platform will POST events to your URL whenever the mapping fires.

Pattern 2: Multiple Tables → One Topic

Aggregate changes from several tables into a single topic for unified consumption.

users table      ─── mapping ───┐
addresses table  ─── mapping ───┤──▶  user.profile.changed  ──▶  subscribers
preferences table ── mapping ───┘

All three mappings target the same topic. Subscribers receive a unified stream of profile-related changes without needing to know which table changed.

Pattern 3: One Table → Multiple Topics

Route different types of changes from the same table to different topics.

                    ┌── mapping (when status='active')   ──▶  session.started
sessions table  ────┤
                    ├── mapping (when status='completed') ──▶  session.ended
                    │
                    └── mapping (any update)              ──▶  session.audit.log

Use mapping filter conditions (when) to route different changes to different topics based on column values.

Pattern 4: SDK Events Without CDC

Publish events directly from application code — no database or mappings needed.

// Your application code publishes directly to a topic
realtime.publish('report.generated', {
  reportId: 'rpt_123',
  format: 'pdf',
  generatedBy: 'system',
});

// Subscribers on 'report.generated' receive the event
// Webhook endpoints on 'report.generated' get HTTP POSTs

No mapping or CDC setup required — the topic is all you need.

Quick Reference

Concept	What it is	Required?	Belongs to
Topic	Named routing channel for events	Yes — every event needs a topic	Application + Environment
Schema	Versioned JSON Schema for payload validation	No — topics work without schemas	A specific Topic
Mapping	CDC rule: table change → topic event	No — only needed for database CDC	Points to a Topic
Webhook	HTTP endpoint that receives events	No — one of many subscriber types	Subscribes to Topics
Subscription	Real-time listener on a topic	No — one of many subscriber types	Subscribes to Topics