# Webhooks Set up webhooks to receive notifications when conversations, participants, or communications change in Conversation Orchestrator. Each notification includes the event type, a timestamp, and the affected resource. To receive webhooks, add one or more status callback URLs to your [conversation configuration](/docs/conversations/orchestrator/concepts/core#conversation-configuration). ## Configure status callbacks Add status callback URLs when you create or update a configuration using the Twilio Console or the [Conversation Orchestrator API reference](/docs/api/conversations/v2). To configure status callbacks in the Console, follow these steps: 1. Sign in to the [Twilio Console](https://1console.twilio.com). 2. Go to **Products & services** > **Conversation Orchestrator** > **Conversation configurations**. 3. Select your conversation configuration. 4. In the **Details** section, click **Edit**. 5. In the **Webhook** section of the **Edit details** modal, enter your webhook URL in the **Callback URL** field and select an **HTTP method**. 6. Click **Save changes**. To configure status callbacks with the API, include the `statusCallbacks` array when you create or update a [Configuration resource](/docs/api/conversations/v2/Configuration). Status callback URLs must use HTTPS with a public host. ## Event types Conversation Orchestrator sends the following event types: | Event type | Description | | ----------------------- | ---------------------------------------------------- | | `CONVERSATION_CREATED` | A new conversation starts. | | `CONVERSATION_UPDATED` | A conversation's status or name changes. | | `PARTICIPANT_ADDED` | A participant joins a conversation. | | `PARTICIPANT_UPDATED` | A participant's details change. | | `PARTICIPANT_REMOVED` | A participant leaves a conversation. | | `COMMUNICATION_CREATED` | A new message or transcription joins a conversation. | | `COMMUNICATION_UPDATED` | A communication's details change. | ## Webhook payload structure Every webhook payload is a JSON object with three top-level properties: | Property | Type | Description | | ----------- | ------ | ------------------------------------------------------------------------------------------ | | `eventType` | string | The event that triggered the webhook. See [Event types](#event-types) for possible values. | | `timestamp` | string | The date and time when the event occurred, in ISO 8601 format (UTC). | | `data` | object | The resource object. The structure depends on the event type. | The structure of the `data` object depends on the event type: * For `CONVERSATION_CREATED` and `CONVERSATION_UPDATED` events, `data` contains a [Conversation resource](#conversation-resource). * For `PARTICIPANT_ADDED`, `PARTICIPANT_UPDATED`, and `PARTICIPANT_REMOVED` events, `data` contains a [Participant resource](#participant-resource). * For `COMMUNICATION_CREATED` and `COMMUNICATION_UPDATED` events, `data` contains a [Communication resource](#communication-resource). ### Conversation resource The `data` object for conversation events contains the following properties: | Property | Type | Description | | ----------------- | ------ | ------------------------------------------------------------------------------------------------ | | `id` | string | The conversation ID. | | `accountId` | string | The account SID. | | `configurationId` | string | The conversation configuration ID. | | `configuration` | object | The conversation configuration, including channel settings, capture rules, and status callbacks. | | `status` | string | The conversation status. Possible values: `ACTIVE`, `INACTIVE`, `CLOSED`. | | `name` | string | The conversation name. | | `createdAt` | string | The date and time when the conversation was created, in ISO 8601 format. | | `updatedAt` | string | The date and time when the conversation was last updated, in ISO 8601 format. | ### Participant resource The `data` object for participant events contains the following properties: | Property | Type | Description | | ---------------- | ---------------- | --------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The participant ID. | | `conversationId` | string | The conversation ID. | | `accountId` | string | The account SID. | | `name` | string | The participant display name. | | `type` | string | The participant type. Possible values: `CUSTOMER`, `HUMAN_AGENT`, `AI_AGENT`, `AGENT`, or `UNKNOWN`. | | `profileId` | string or null | The profile ID associated with [Conversation Memory](/docs/conversations/memory). It's resolved for `CUSTOMER` participants only. | | `addresses` | array of objects | The participant's communication addresses. Each object contains `address`, `channel`, and `channelId`. | | `createdAt` | string or null | The date and time when the participant was added, in ISO 8601 format. | | `updatedAt` | string or null | The date and time when the participant was last updated, in ISO 8601 format. | ### Communication resource The `data` object for communication events contains the following properties: | Property | Type | Description | | ---------------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | string | The communication ID. | | `conversationId` | string | The conversation ID. | | `accountId` | string | The account SID. | | `author` | object | The sender's address. Contains `address`, `channel`, and `participantId`. | | `content` | object | The communication content, which includes a `type` field (`TEXT` or `TRANSCRIPTION`), the message `text`, and, for voice transcriptions, a `transcription` object with word-level timing data. | | `channelId` | string | The channel-specific reference ID (for example, a Message SID or Call SID). | | `recipients` | array of objects | The recipients of the communication. Each object contains `address`, `channel`, `participantId`, and `deliveryStatus`. | | `occurredAt` | string | The date and time when the communication occurred, in ISO 8601 format. | | `createdAt` | string | The date and time when the communication was created, in ISO 8601 format. | | `updatedAt` | string | The date and time when the communication was last updated, in ISO 8601 format. | #### Delivery status values The `deliveryStatus` field on each recipient has one of the following values: | Value | Description | | ------------- | --------------------------------------------------------------------------------- | | `INITIATED` | The communication is queued to send. | | `IN_PROGRESS` | The communication is being sent. | | `DELIVERED` | The provider confirms delivery. | | `COMPLETED` | For voice, the call has ended. For messaging, the recipient has read the message. | | `FAILED` | The communication couldn't be sent or delivered. | ## Webhook payload examples ### CONVERSATION\_CREATED ```json { "eventType": "CONVERSATION_CREATED", "timestamp": "2026-03-31T16:32:51.345476911Z", "data": { "id": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz", "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "configuration": { "channelSettings": { "SMS": { "captureRules": [ { "from": "*", "to": "+15551234567", "metadata": {} }, { "from": "+15551234567", "to": "*", "metadata": {} } ], "statusTimeouts": { "closed": 15, "inactive": null } }, "VOICE": { "captureRules": [], "statusTimeouts": null } }, "conversationGroupingType": "GROUP_BY_PARTICIPANT_ADDRESSES_AND_CHANNEL_TYPE", "description": "Configuration for support interactions", "displayName": "support-conversations", "intelligenceConfigurationIds": [], "memoryExtractionEnabled": true, "memoryStoreId": "mem_store_01kfp5sj35ecqsvff0b2vn77wr", "redaction": null, "statusCallbacks": [ { "url": "https://example.com/webhook", "method": "POST" } ] }, "configurationId": "conv_configuration_01km10y03se0dakjayz4vnxybc", "createdAt": "2026-03-31T16:32:51.254049339Z", "name": "Auto-generated conversation", "status": "ACTIVE", "updatedAt": "2026-03-31T16:32:51.254049558Z" } } ``` ### PARTICIPANT\_ADDED ```json { "eventType": "PARTICIPANT_ADDED", "timestamp": "2026-03-31T16:32:51.346215804Z", "data": { "id": "conv_participant_01kn2bv81nfh9826g8cthk73ak", "conversationId": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz", "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "name": "+15559876543", "addresses": [ { "channel": "SMS", "address": "+15559876543", "channelId": null } ], "createdAt": null, "profileId": "mem_profile_01kg5rdy0af2jtrjfr7vpxsaad", "type": "CUSTOMER", "updatedAt": null } } ``` ### COMMUNICATION\_CREATED ```json { "eventType": "COMMUNICATION_CREATED", "timestamp": "2026-03-31T16:32:51.353676996Z", "data": { "id": "conv_communication_01kn2bv81ff44r5h81ar7r1z69", "conversationId": "conv_conversation_01kn2bv81ne86bpt2ad7wafpqz", "accountId": "ACXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "author": { "address": "+15559876543", "channel": "SMS", "participantId": "conv_participant_01kn2bv81nfh9826g8cthk73ak" }, "content": { "type": "TEXT", "text": "Hello, I need help with my order" }, "recipients": [ { "address": "+15551234567", "channel": "SMS", "participantId": "conv_participant_01kn2bv81nfvfr1j2mdesj84z2", "deliveryStatus": "DELIVERED" } ], "channelId": "SM5f4c40fd4643b8394bc0fe83e3d20ca9", "createdAt": "2026-03-31T16:32:51.343567735Z", "occurredAt": "2026-03-31T16:32:51.247963992Z", "updatedAt": "2026-03-31T16:32:51.343573651Z" } } ``` ## Next steps * [Core concepts](/docs/conversations/orchestrator/concepts/core): The object model for conversations, participants, and communications. * [Conversation lifecycle](/docs/conversations/orchestrator/concepts/lifecycle): How conversations move between `ACTIVE`, `INACTIVE`, and `CLOSED`. * [Conversation Orchestrator API reference](/docs/api/conversations/v2): Full API details for webhooks and status callbacks.