Connect webhooks and events

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.

Connect

Concepts

Reference

Connect webhooks and events

Events

Payloads

Webhook event types

Connect API reference

​Events

​Payloads

Webhook event types

Connect API reference

Events

Payloads