Skip to main content
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

Every callback Vobiz sends includes HMAC-SHA256 signatures in the request headers (X-Vobiz-Signature-V2, X-Vobiz-Signature-V3, and their multi-account variants). Validate these signatures to confirm the request genuinely came from Vobiz and was not tampered with.

Validating Callbacks

Full validation guide with code examples in Python, Node.js, Go, and Ruby.

​
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.