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.

Vobiz supports real-time HTTP webhook notifications on SIP trunk calls. Configure a webhook URL on any trunk to receive callbacks for two events: when a call is initiated (admitted or rejected) and when a call ends (with full details including duration, cost, and quality metrics).
Configure in the ConsoleWebhook URL and method are configured per trunk in the Vobiz Console → SIP → Outbound Trunks. You can also set them when creating or updating a trunk via the API.

​
Configuration

Each trunk can optionally have a webhook configured with two fields:
FieldTypeDescription
webhook_urlstringYour publicly accessible HTTP endpoint (max 500 characters). Private IPs, localhost, and AWS metadata endpoints are blocked.
webhook_methodstringHTTP method for the callback. Accepts POST (default) or GET.

​
Security validation

When a webhook URL is configured, Vobiz validates it against SSRF attacks before accepting it. The following are blocked:
  • Schemes: Only http and https are allowed.
  • Localhost: 127.0.0.1, ::1, and 0.0.0.0 are blocked.
  • Private IP ranges: 10.0.0.0/8, 172.16.0.0/12, and 192.168.0.0/16 are blocked.
  • Link-local addresses: 169.254.0.0/16 is blocked, including the AWS metadata endpoint (169.254.169.254).
  • IPv6: ULA (fc00::/7) and multicast (ff00::/8) addresses are blocked.

​
Webhook events

Vobiz delivers two event types to your configured webhook URL.

​
CallInitiated

Fired for every outbound call attempt during call admission, whether the call is allowed or rejected. Use this event for real-time call monitoring and rejection alerting. Fires when:
  • Call is admitted - Allowed: true
  • Call is rejected - Allowed: false with a Reason
Possible rejection reasons:
  • Insufficient balance
  • CLI ownership validation failed
  • Aadhaar verification pending
  • KYC verification required
  • Rate limit or concurrent call limit exceeded
  • No routes available
{
  "Event": "CallInitiated",
  "CallUUID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "RequestID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Timestamp": "2026-03-18T12:00:00Z",
  "From": "+919876543210",
  "To": "+918012345678",
  "Direction": "outbound",
  "Status": "initiated",
  "auth_id": "MA_XXXXXXXX",
  "TrunkID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "10.0.0.1",
  "SIPCallID": "abc123@10.0.0.1",
  "Allowed": true,
  "Reason": ""
}

​
Hangup

Fired when a call ends. Includes the full call record - duration, billable seconds, ring time, cost, currency, and voice quality metrics (MOS score and jitter).
FieldTypeDescription
DurationintegerTotal call duration in seconds (ring + talk time).
BillsecintegerBillable seconds - time the call was actually connected.
RingTimeintegerTime in seconds the call rang before being answered.
CostfloatCall cost deducted from account balance.
CurrencystringCurrency of the cost (e.g. INR).
MOSfloatMean Opinion Score - voice quality (1.0–5.0, higher is better).
JitterintegerNetwork jitter in milliseconds. Lower is better.
Hangup Payload
{
  "Event": "Hangup",
  "CallUUID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "RequestID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Timestamp": "2026-03-18T12:05:00Z",
  "From": "+919876543210",
  "To": "+918012345678",
  "Direction": "outbound",
  "Status": "completed",
  "auth_id": "MA_XXXXXXXX",
  "TrunkID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "10.0.0.1",
  "SIPCallID": "abc123@10.0.0.1",
  "Allowed": true,
  "Reason": "NORMAL_CLEARING",
  "StartTime": "2026-03-18T12:00:00Z",
  "EndTime": "2026-03-18T12:05:00Z",
  "Duration": 300,
  "Billsec": 295,
  "RingTime": 5,
  "Cost": 1.50,
  "Currency": "INR",
  "MOS": 4.2,
  "Jitter": 15
}

​
HTTP request details

​
Headers sent with every webhook

HeaderValue
Content-Typeapplication/json
User-AgentVobiz-Vapor/1.0
X-Vobiz-EventCallInitiated or Hangup
X-Vobiz-Request-IDUnique request identifier

​
Timeouts

PhaseTimeout
Call admission webhook (CallInitiated)10 seconds
Hangup webhook - CDR to Vapor5 seconds
Hangup webhook - Vapor to customer endpoint10 seconds

​
Behavior & reliability

​
Non-blocking

All webhooks are sent asynchronously. Webhook requests never delay the SIP call flow - call admission and CDR processing proceed independently of webhook delivery.

​
Fail-open

Webhook failures do not affect calls:
  • If the webhook URL is unreachable, the call still proceeds normally.
  • Non-2xx responses are logged but do not affect the call.
  • Network timeouts are logged as errors with no retry.

​
Informational only

Webhooks are one-way notifications. The response from your endpoint does not influence call routing, billing, or any platform behavior. You cannot accept or reject calls via a webhook response.