Skip to main content
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.

​
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.

​
Webhook request body

The webhook request body contains a JSON payload representing events emitted by the agent system. Each event includes a unique identifier, timestamp, agent and conversation identifiers, and a payload containing the specific event data. The payload structure varies depending on the event type (setup, ended, custom fields updated, etc.) and contains the relevant information for that particular event. 
{
  "id": "ev_8qm9JBCiTe7",
  "created_at": "2024-01-15T10:30:00Z",
  "agent_id": "ca_8qm9JBCiTe7@v0",
  "conversation_id": "conv_8qm9JBCiTe7",
  "payload": {
    "type": "conversation.setup",
    "data": {
      // Event-specific data based on the event type
    }
  }
}

​
Event types

As of today, Operator delivers webhooks for the following event types, for the full schema of these events refer to the Events schema page:

​
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:
  • Dynamic configuration: learn how to customize your agent dynamically at the start of a conversation by replying to the conversation.setup webhook with configuration data
  • Conversation context: learn how context data is used to customize the agent prompt for a conversation

​
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.
⌘I