Skip to main content

Domain Events

This is the catalog of events Cortex emits. The same events are delivered over webhooks, Server-Sent Events and serverless functions — so this reference applies no matter which surface you consume.

The envelope​

Every event is a DomainEvent:

interface DomainEvent<T> {
  id: string;          // unique id — dedupe on this
  type: string;        // e.g. "message.created"
  source: string;      // emitting service
  tenantId: string;
  projectId?: string;
  resourceId: string;  // affected resource, e.g. "session:abc-123"
  timestamp: string;   // ISO-8601
  payload: ActionPayload<T>;
}

Action-typed payloads​

Every payload is discriminated on an action:

ActionMeaningShape
createdA new entity{ action, data }
updatedAn entity changed{ action, data, changes } — changes holds the old values of fields that differed
deletedAn entity was removed{ action, data } — data is the last known state
occurredA lifecycle moment (no create/update/delete){ action, data }

On updated, changes lets you see exactly what changed without keeping your own copy. Nested objects are atomic — if any field within one changes, the whole previous nested object is included.

Subscribing​

  • Webhooks — list event names when creating a subscription. Wildcards are supported: exact (message.created), domain (message.*) or global (*).
  • Functions — export a handler named after the event (message.created → onMessageCreated). The subscription is derived from your exports.
  • SSE — open the event stream (the SDK’s watch() does this for you) and filter by type.

Catalog​

Session​

TypeActionEmitted when
session.createdcreatedA session is created
session.updatedupdatedA session changes (e.g. status)
session.deleteddeletedA session is deleted

Message​

TypeActionEmitted when
message.createdcreatedA transcribed utterance is stored

Participant​

TypeActionEmitted when
participant.createdcreatedA participant first appears in a project
participant.updatedupdatedA participant changes (display name, email, user data)
participant.deleteddeletedA participant is deleted
participant.joinedoccurredA participant joined a session or gathering
participant.leftoccurredA participant left a session or gathering

Annotation​

TypeActionEmitted when
message.annotation.createdcreatedA plugin produced a message-scoped annotation
session.annotation.createdcreatedA plugin produced a session-scoped annotation

Annotation events carry the plugin-defined body under a content object, and a resourceId pointing at the annotated entity (message:{id} or session:{id}).

Sanction​

TypeActionEmitted when
sanction.createdcreatedA moderation action is applied
sanction.updatedupdatedA sanction is modified
sanction.revokedoccurredA sanction is lifted

Gathering​

TypeActionEmitted when
gathering.createdcreatedA gathering is created
gathering.updatedupdatedA gathering changes
gathering.startedoccurredA gathering starts (optionally creating a session)
gathering.endedoccurredA gathering ends
gathering.cancelledoccurredA gathering is cancelled before it starts

Gathering members​

TypeActionEmitted when
gathering.member.joinedoccurredA member joined
gathering.member.readyoccurredA member marked ready (lobby)
gathering.member.leftoccurredA member left

Gathering invitations​

TypeActionEmitted when
gathering.invitation.sentoccurredAn invitation was created (email may be queued)
gathering.invitation.acceptedoccurredAn invitee accepted
gathering.invitation.declinedoccurredAn invitee declined

Bot​

TypeActionEmitted when
bot.status.changedoccurredThe transcription bot changed status (starting / running / stopped / error)

Webhook delivery (meta)​

TypeActionEmitted when
webhook.delivery.updatedupdatedA webhook delivery changed status (delivered / failed / retrying)

Example​

A message.created event delivered to a webhook or function:

{
  "id": "8f3c…",
  "type": "message.created",
  "source": "cortex:bot",
  "tenantId": "…",
  "projectId": "…",
  "resourceId": "session:abc-123",
  "timestamp": "2026-06-04T10:00:00.000Z",
  "payload": {
    "action": "created",
    "data": {
      "messageId": "…",
      "sessionId": "abc-123",
      "participantId": "…",
      "content": "Hello everyone, let's get started."
    }
  }
}