> ## Documentation Index
> Fetch the complete documentation index at: https://docs.open.cx/llms.txt
> Use this file to discover all available pages before exploring further.

# 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 `x-opencx-signature` HMAC verification used by [all OpenCX webhooks](/api-reference/webhooks/types).

## 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`

```typescript theme={"dark"}
{
  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`

```typescript theme={"dark"}
{
  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`

```typescript theme={"dark"}
{
  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`

```typescript theme={"dark"}
{
  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;
  };
}
```

<Tip>
  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.
</Tip>

<CardGroup cols={2}>
  <Card title="Webhook event types" icon="globe" href="/api-reference/webhooks/types">
    Signature verification, retries, and the platform-wide event catalog.
  </Card>

  <Card title="Connect API reference" icon="code" href="/api-reference/connect/index">
    The REST surface these events mirror.
  </Card>
</CardGroup>