When building on Operator, you may want your agents to send real-time events to your application as they run, allowing your backend systems to execute actions accordingly. To receive webhooks, go to Developers → Webhooks and set your webhook endpoint URL. Once you’ve set the endpoint, your agents will push real-time event data to your application’s webhook endpoint when events happen in your Operator account. We deliver events through HTTPS POST requests with a JSON payload. For details on event types and schema, refer to the Real-time chat session WebSocket API documentation.

​
Verification

All webhook requests are HMAC-signed to ensure request authenticity and prevent replay attacks. You can find your signing key at Developers → Webhooks. Learn more about this scheme in First-party APIs → Authentication.

​
Event types

We currently send webhooks for the following event types:

​
conversation.setup

This webhook is sent when a conversation is being set up—for example, when an agent is about to dial a call or has received a call but hasn’t yet picked up. You can return the following configuration and data to this webhook request (similar to the configuration for a new outbound conversation):
context
object
required
JSON object that will be used as context for the conversation. This is the only way to load context into conversations that aren’t triggered by an API call, such as incoming phone calls.
override_config
object
Partial override for the agent’s configuration (e.g. voice, runtime, tools). Follows the same shape as the agent configuration object, but all fields are optional since it is merged into the base config.
Read more:

​
conversation.ended

This webhook is sent when the conversation completes. At this point, you’re guaranteed that the conversation has terminated and will have a status of one of the following: completed, failed, busy, no-answer or voicemail.

​
conversation.custom_fields.updated

This webhook is sent when a custom field on a conversation is modified. The webhook includes the key that was updated, along with both the new value and the previous value (if any). This allows you to track changes to custom fields and trigger downstream workflows based on field updates.