Vobiz Webhook (Callback) Configuration

Quick setup: Callbacks can be configured at multiple levels: account-wide defaults, per-application, per-trunk, or per-call. More specific configurations override broader ones.

Configuring Callbacks

Callback URL Requirements

✓ Must use HTTPS (not HTTP)
✓ Must be publicly accessible (not localhost)
✓ Must respond within 3 seconds
✓ Must return HTTP 200 status code
✓ Should handle POST requests
✓ Should accept application/x-www-form-urlencoded content type (form data)

Callback Configuration Hierarchy

Callbacks are resolved in this order (most specific to least specific):

Per-Call Callback

Callback URL specified when making a call.status_url parameter in Make Call API

Application Callback

Callback configured in Application settings.callback_url in Application object

Trunk Callback

Callback configured on SIP Trunk.status_callback in Trunk configuration

Account Default

Account-wide default callback URL.default_callback_url in Account settings

Application Callbacks

Configure Application Callback

Set up callbacks when creating or updating an application:

Create Application with Callback

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/applications/

{
  "name": "Customer Support App",
  "callback_url": "https://api.yourapp.com/webhooks/vobiz/calls",
  "callback_method": "POST",
  "fallback_callback_url": "https://backup.yourapp.com/webhooks/vobiz/calls",
  "callback_events": [
    "Ring",
    "StartApp",
    "Hangup",
    "recording.completed"
  ]
}

Application Callback Parameters

Field	Type	Required	Description
`callback_url`	string	No	HTTPS URL to receive callbacks
`callback_method`	string	No	HTTP method (POST or GET). Default: POST
`fallback_callback_url`	string	No	Fallback URL if primary callback fails
`callback_events`	array	No	Array of event types to receive. If empty, receives all events.

Trunk Callbacks

Configure Trunk Status Callback

Receive callbacks for all calls through a specific trunk:

Update Trunk with Callback

PUT https://api.vobiz.ai/api/v1/Account/{auth_id}/trunks/{trunk_id}

{
  "status_callback": "https://api.yourapp.com/webhooks/trunk-events",
  "status_callback_method": "POST",
  "status_callback_events": [
    "Ring",
    "StartApp",
    "Hangup",
    "call.failed"
  ]
}

Trunk Callback Use Cases

Call Tracking: Monitor all calls through a specific trunk
Department Routing: Different callbacks for sales vs support trunks
Billing Integration: Track usage per trunk for chargeback
Quality Monitoring: Collect metrics for specific carriers/trunks

Call-Level Callbacks

Per-Call Callback Configuration

Override application/trunk callbacks for specific calls:

Make Call with Custom Callback

POST https://api.vobiz.ai/api/v1/Account/{auth_id}/calls/

{
  "from": "+14155551234",
  "to": "+14155555678",
  "status_url": "https://api.yourapp.com/webhooks/specific-call",
  "status_method": "POST"
}

Callback Authentication

To verify that callbacks originate from Vobiz, configure shared secrets and verify HMAC signatures. See Callbacks for verification code examples.

Testing Callbacks

For local development, use a tunneling service like ngrok to expose your local server publicly:

ngrok http 3000

Then use the ngrok URL (e.g. https://abc123.ngrok.io/webhooks/vobiz) as your callback URL.

Vobiz retries failed callbacks (non-200 responses) up to 3 times with exponential backoff. Make your callback handlers idempotent to handle duplicate deliveries safely.

Getting Started

Using Vobiz Platform

Compliance (India)

Tools

Vobiz Webhook (Callback) Configuration

Configuring Callbacks

Callback URL Requirements

Callback Configuration Hierarchy

Application Callbacks

Configure Application Callback

Application Callback Parameters

Trunk Callbacks

Configure Trunk Status Callback

Trunk Callback Use Cases

Call-Level Callbacks

Per-Call Callback Configuration

Callback Authentication

Testing Callbacks

​Configuring Callbacks

​Callback URL Requirements

​Callback Configuration Hierarchy

​Application Callbacks

​Configure Application Callback

​Application Callback Parameters

​Trunk Callbacks

​Configure Trunk Status Callback

​Trunk Callback Use Cases

​Call-Level Callbacks

​Per-Call Callback Configuration

​Callback Authentication

​Testing Callbacks

Configuring Callbacks

Callback URL Requirements

Callback Configuration Hierarchy

Application Callbacks

Configure Application Callback

Application Callback Parameters

Trunk Callbacks

Configure Trunk Status Callback

Trunk Callback Use Cases

Call-Level Callbacks

Per-Call Callback Configuration

Callback Authentication

Testing Callbacks