Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.vobiz.ai/llms.txt

Use this file to discover all available pages before exploring further.

What are callbacks? When events occur in your Vobiz account (a call completing, a recording finishing, a conference ending), Vobiz automatically sends HTTP POST requests to your server with details about the event. This lets your application react to events in real time without polling.

​
How Callbacks Work

1

Configure Callback URL

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

Event Occurs

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

Vobiz Sends HTTP POST

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

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/x-www-form-urlencoded
User-Agent: Vobiz-Webhook/1.0

{
  "Event": "Hangup",
  "CallUUID": "550e8400-e29b-41d4-a716-446655440000",
  "From": "+14155551234",
  "To": "+14155555678",
  "Status": "completed",
  "Duration": 125,
  "StartTime": "2025-10-30T10:30:00Z",
  "EndTime": "2025-10-30T10:32:05Z",
  "Direction": "outbound",
  "auth_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 TypeDescriptionWhen It’s Sent
RingCall is ringingWhen outbound call starts ringing (via /answer)
StartAppCall was answeredWhen the called party answers (via /answer)
HangupCall has endedWhen call completes (via /answer)
recording.completedRecording is readyWhen recording finishes processing
conference.startedConference has startedWhen first participant joins
conference.endedConference has endedWhen last participant leaves

​
Callback Parameters

​
Standard Parameters

All callback requests include these standard parameters:
ParameterTypeDescription
EventstringEvent type identifier (e.g., Ring, StartApp, Hangup)
timestampstringISO 8601 timestamp of when event occurred
auth_idstringYour Vobiz account identifier
CallUUIDstringUnique identifier for the call

​
Security Considerations

​
Always Use HTTPS

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

​
Verify Callback Source

Verify that callbacks originate 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.