Connect webhooks and events

Every Connect event streamed to your backend — thread lifecycle, messages with translations, participant changes, Supervisor interventions and escalations.

Connect emits webhooks for everything that happens in a thread, so your backend can mirror messages into your own systems, trigger ops flows on escalations, and audit Supervisor activity. Configure endpoints in Settings → Webhooks — Connect events share the delivery pipeline, retry policy, and svix-signature HMAC verification used by all OpenCX webhooks.

Events

Event	Fires when
connect.thread.created	A thread is created
connect.thread.status_changed	open → wrap_up → locked → archived, or order_status changes
connect.participant.added	A participant joins (e.g. courier assigned)
connect.participant.removed	A participant is removed (e.g. courier reassigned)
connect.message.created	Any participant or the Supervisor sends a message
connect.supervisor.intervened	The Supervisor acts: answer, nudge, safety mask
connect.supervisor.escalated	A thread escalates into a support session

Payloads

All events share the standard envelope: event, organization_id, data, and an ISO timestamp.

connect.message.created

{
  event: 'connect.message.created';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;              // your order ID
    lane: 'customer_merchant' | 'customer_courier' | 'merchant_courier';
    message: {
      id: string;
      sender: { participant_id: string; role: 'customer' | 'merchant' | 'courier' | 'supervisor' };
      text: string;                 // original text (post safety-masking)
      translations: Record<string, string>;   // e.g. { ar: '...', en: '...' }
      attachments: { url: string; content_type: string }[];
      created_at: string;
    };
  };
}

connect.supervisor.intervened

{
  event: 'connect.supervisor.intervened';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    lane: string;
    kind: 'answer' | 'nudge' | 'safety_mask' | 'off_platform_flag';
    detail: string;                 // human-readable description
    message_id?: string;            // present when the intervention produced a message
    timestamp: string;
  };
}

connect.supervisor.escalated

{
  event: 'connect.supervisor.escalated';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    session_id: string;             // the OpenCX session opened in your inbox
    reason: 'sentiment' | 'unanswered' | 'requested_human' | 'prohibited_topic' | 'safety';
    summary: string;                // the context handed to your team
    timestamp: string;
  };
}

connect.thread.status_changed

{
  event: 'connect.thread.status_changed';
  organization_id: string;
  data: {
    thread_id: string;
    reference: string;
    status: 'open' | 'wrap_up' | 'locked' | 'archived';
    order_status: string;
    timestamp: string;
  };
}

Going headless (your own chat UI)? Subscribe to connect.message.created and render from the translations map for each viewer’s language — the same data the drop-in component uses.

Webhook event types

Signature verification, retries, and the platform-wide event catalog.

Connect API reference

The REST surface these events mirror.