Callbacks

Callbacks (also known as webhooks) are HTTP requests that Vobiz sends to your server to notify you about events in real-time. They enable asynchronous communication and event-driven architectures.

What Are Callbacks?

When events occur in your Vobiz account (such as a call completing, a recording finishing, or a conference ending), Vobiz can automatically send HTTP POST requests to your server with detailed information about the event.

This allows your application to react to events in real-time without constantly polling our API for updates.

How Callbacks Work

The Callback Flow

Configure Callback URL

You provide a callback URL when creating resources (applications, trunks, calls, etc.)

Event Occurs

An event happens in your account (call ends, recording completes, etc.)

Vobiz Sends HTTP POST

Vobiz sends an HTTP POST request to your callback URL with event details

Your Server Responds

Your server processes the callback and responds with HTTP 200 OK

Example Callback Request

When a call ends, Vobiz sends a POST request to your callback URL:

POST Request to Your Callback URL

POST /webhooks/call-status HTTP/1.1
Host: your-domain.com
Content-Type: application/json
User-Agent: Vobiz-Webhook/1.0

{
  "event": "call.completed",
  "call_id": "550e8400-e29b-41d4-a716-446655440000",
  "from": "+14155551234",
  "to": "+14155555678",
  "status": "completed",
  "duration": 125,
  "start_time": "2025-10-30T10:30:00Z",
  "end_time": "2025-10-30T10:32:05Z",
  "direction": "outbound",
  "account_id": "{Auth_ID}"
}

Example Server Response

Your server should respond with HTTP 200 to acknowledge receipt:

Your Server Response

HTTP/1.1 200 OK
Content-Type: application/json

{
  "status": "received"
}

Callback Events

Event Type	Description	When It's Sent
call.initiated	Call has been initiated	When outbound call starts ringing
call.answered	Call was answered	When the called party answers
call.completed	Call has ended	When call completes (any reason)
recording.completed	Recording is ready	When recording finishes processing
conference.started	Conference has started	When first participant joins
conference.ended	Conference has ended	When last participant leaves

Callback Parameters

Standard Parameters

All callback requests include these standard parameters:

Parameter	Type	Description
event	string	Event type identifier
timestamp	string	ISO 8601 timestamp of when event occurred
account_id	string	Your Vobiz account identifier
resource_id	string	ID of the resource (call_id, conference_id, etc.)

Security Considerations

Always Use HTTPS

Important: Only use HTTPS URLs for callback endpoints. HTTP URLs are not supported for security reasons.

Verify Callback Source

Implement verification to ensure callbacks are genuinely from Vobiz:

Verify Callback Signature

const crypto = require('crypto');

function verifyCallback(request, secret) {
  const signature = request.headers['x-vobiz-signature'];
  const timestamp = request.headers['x-vobiz-timestamp'];
  const body = JSON.stringify(request.body);

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

  // Verify signature
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(timestamp + '.' + body)
    .digest('hex');

  return signature === expectedSignature;
}

Implement Replay Protection

Store processed callback IDs to prevent replay attacks:

Check if callback ID has been processed before
Store callback IDs in cache/database for 24 hours
Reject duplicate callbacks with same ID

Best Practices

Respond Quickly

Return HTTP 200 within 3 seconds. If processing takes longer, queue the callback for async processing and respond immediately.

Handle Retries

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

Log Everything

Log all incoming callbacks with full payload for debugging. Include timestamps, event types, and processing results.

Monitor Callback Health

Track callback success/failure rates, response times, and set up alerts for failures. Monitor for missing callbacks as a sign of delivery issues.

Use Separate Endpoints

Consider using different callback URLs for different event types or resources to simplify routing and processing logic.

Concepts Overview

Callback Configurations