Callback Configurations

Learn how to configure callback URLs across different Vobiz resources. Set up endpoints to receive real-time event notifications for calls, conferences, recordings, and more.

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/json content type

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_callback_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 /api/v1/account/{account_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": [
    "call.initiated",
    "call.answered",
    "call.completed",
    "recording.completed"
  ]
}

Application Callback Parameters

Request Parameters

Name	Type	Description
`callback_url`	string	HTTPS URL to receive callbacks
`callback_method`	string	HTTP method (POST or GET). Default: POST
`fallback_callback_url`	string	Fallback URL if primary callback fails
`callback_events`	array	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 /api/v1/account/{account_id}/trunks/{trunk_id}

{
  "status_callback": "https://api.yourapp.com/webhooks/trunk-events",
  "status_callback_method": "POST",
  "status_callback_events": [
    "call.initiated",
    "call.answered",
    "call.completed",
    "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 /api/v1/account/{account_id}/calls/

{
  "from": "+14155551234",
  "to": "+14155555678",
  "answer_url": "https://api.yourapp.com/xml/call-flow",
  "status_callback_url": "https://api.yourapp.com/webhooks/important-call",
  "status_callback_method": "POST",
  "status_callback_events": [
    "initiated",
    "answered",
    "completed"
  ]
}

When to Use Call-Level Callbacks

• High-priority calls that need special tracking
• A/B testing different callback handlers
• Customer-specific webhook endpoints
• Temporary overrides for debugging

Callback Authentication

Basic Authentication

Include credentials in the callback URL:

Callback URL with Basic Auth

https://username:password@api.yourapp.com/webhooks/vobiz

Note: While this works, we recommend using signature verification instead of basic auth for better security.

Signature Verification (Recommended)

Verify callbacks using HMAC signatures:

Express.js Callback Handler with Signature Verification

const express = require('express');
const crypto = require('crypto');

const app = express();
app.use(express.json());

const WEBHOOK_SECRET = process.env.VOBIZ_WEBHOOK_SECRET;

function verifySignature(req) {
  const signature = req.headers['x-vobiz-signature'];
  const timestamp = req.headers['x-vobiz-timestamp'];

  if (!signature || !timestamp) {
    return false;
  }

  // Verify timestamp is recent (within 5 minutes)
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - timestamp) > 300) {
    return false;
  }

  // Compute expected signature
  const payload = timestamp + '.' + JSON.stringify(req.body);
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhooks/vobiz/calls', (req, res) => {
  // Verify signature
  if (!verifySignature(req)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  // Process callback
  const event = req.body.event;
  const callId = req.body.call_id;

  console.log(`Received ${event} for call ${callId}`);

  // Queue for async processing
  queueCallback(req.body);

  // Respond immediately
  res.status(200).json({ status: 'received' });
});

Custom Headers

Add custom headers to callback requests for additional authentication:

Configure Custom Headers

{
  "callback_url": "https://api.yourapp.com/webhooks/vobiz",
  "callback_headers": {
    "X-API-Key": "your-secret-api-key",
    "X-Application-ID": "app-12345"
  }
}

Testing Callbacks

Use webhook.site for Quick Testing

For development and testing, use services like webhook.site to inspect callback payloads:

Visit https://webhook.site and copy your unique URL
Configure this URL as your callback URL
Trigger events (make calls, etc.)
Inspect callback payloads in webhook.site UI

Local Development with ngrok

Test callbacks on your local machine using ngrok:

Set up ngrok tunnel

# Install ngrok
npm install -g ngrok

# Start your local server (e.g., port 3000)
node server.js

# Create public tunnel
ngrok http 3000

# Use the ngrok HTTPS URL as your callback URL
# Example: https://abc123.ngrok.io/webhooks/vobiz

Test Callback Handler

Create a simple test to verify your callback handler works:

Test Callback Endpoint

const axios = require('axios');

async function testCallback() {
  const mockCallbackData = {
    event: 'call.completed',
    call_id: 'test-call-123',
    from: '+14155551234',
    to: '+14155555678',
    status: 'completed',
    duration: 125,
    account_id: 'MA_TEST123'
  };

  try {
    const response = await axios.post(
      'https://yourdomain.com/webhooks/vobiz/calls',
      mockCallbackData,
      {
        headers: {
          'Content-Type': 'application/json',
          'User-Agent': 'Vobiz-Webhook/1.0'
        }
      }
    );

    console.log('✓ Callback handler responded:', response.status);
  } catch (error) {
    console.error('✗ Callback handler failed:', error.message);
  }
}

testCallback();

Monitor Callback Delivery

Set up monitoring and alerting for callback failures: • Track callback success/failure rates
• Alert on consecutive failures (3+)
• Monitor callback response times
• Log all callback attempts with outcomes

Callbacks

XML Reference Overview