Available Webhooks

Ultravox offers several webhook events that you can subscribe to for real-time notifications. Each event provides detailed information about what happened in your account.

​

Available Events

The following events are available and can be specified when creating or updating a webhoook.

​

Event Payload Reference

All webhooks follow a consistent structure. The payload always includes:

• event: The type of event that triggered the webhook.
• call: Complete call object matching our API response format.

{
  "event": {event_name},
  "call": {call_object}
}

{
  "event": {event_name},
  "call": {call_object}
}

{
  "event": "call.started",
  "call": {
    "callId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "clientVersion": "<string>",
    "created": "2023-11-07T05:31:56Z",
    "...": "..."
  }
}

​

Event Name

The event field contains the exact event name you subscribed to:

• "call.started"
• "call.ended"
• "call.joined"

​

Call Object

The call object contains the complete call definition, identical to what you’d receive from the Get Call API endpoint. This ensures consistency across your application whether you’re receiving webhook data or making API requests.

Key call object fields:

• callId: Unique call identifier
• created: Timestamp when call was created
• joined: Timestamp when call was joined
• ended: Timestamp when call was ended
• shortSummary: Short summary of the call
• metadata: Custom metadata you’ve associated with the call

See the Call definition schema for the complete list of fields.

​

Webhook Configuration

When creating or updating a webhook, specify which events you want to receive:

curl -X POST https://api.ultravox.ai/api/webhooks \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhooks/ultravox",
    "events": ["call.started", "call.ended"],
    "secrets": ["your-webhook-secret"]
  }'

​

HTTP Requirements

Your webhook endpoint must meet these requirements:

Accept POST Requests: All webhooks are sent as HTTP POST requests.

Return 2xx Status: Return any 2xx status code (we recommend 204) to acknowledge receipt.

Respond Quickly: Respond quickly to avoid timeouts.

Handle JSON: Parse the JSON payload from the request body.

// Express.js webhook handler example
app.post('/ultravox-webhook', (req, res) => {
  const event = req.body;
  
  switch (event.event) {
    case 'call.started':
      console.log('Call started:', event.call.callId);
      // Initialize any required resources
      break;
      
    case 'call.joined':
      console.log('User joined call:', event.call.callId);
      // Update UI, start monitoring, etc.
      break;
      
    case 'call.ended':
      console.log('Call ended:', event.call.callId, 'Reason:', event.call.endReason);
      // Clean up resources, analyze results, etc.
      break;
  }
  
  res.status(200).send('OK');
});

​

Error Responses

If your endpoint returns a non-2xx status code (e.g. 4xx or 5xx), Ultravox will retry delivery. See Error Handling & Retries for more details.

​

Testing Webhooks

During development, consider using tools like:

• ngrok: Expose local development servers to receive webhooks
• webhook.site: Test webhook payloads without writing code
• Postman: Mock webhook endpoints for testing

Remember that webhook events reflect real activity in your Ultravox account, so test carefully to avoid processing duplicate or test data in production systems.