Trunk Webhooks

Vobiz supports real-time HTTP webhook notifications on SIP trunk calls. Configure a webhook URL on any trunk to receive callbacks when a call is initiated (admitted or rejected), when a call ends (with full details including duration, cost, and quality metrics), and when a call recording is ready (if recording is enabled on the trunk).

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:

Field	Type	Description
`webhook_url`	string	Your publicly accessible HTTP endpoint (max 500 characters). Private IPs, localhost, and AWS metadata endpoints are blocked.
`webhook_method`	string	HTTP 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 three event types to your configured webhook URL. recording.completed is sent only when recording is enabled on the trunk.

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": ""
}

{
  "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": false,
  "Reason": "Insufficient balance: 0.50 INR"
}

Hangup

Fired when a call ends. Includes the full call record - duration, billable seconds, ring time, cost, currency, voice quality (MOS), the bridged-leg UUID, and hangup cause details (name, code, and which party released the call).

Field	Type	Description
`Duration`	integer	Total call duration in seconds (ring + talk time).
`Billsec`	integer	Billable seconds - time the call was actually connected.
`RingTime`	integer	Time in seconds the call rang before being answered.
`Cost`	float	Call cost deducted from account balance.
`Currency`	string	Currency of the cost (e.g. INR).
`MOS`	float	Mean Opinion Score - voice quality (1.0–5.0, higher is better).
`BridgeUUID`	string	UUID of the bridged (B-leg) call.
`HangupCauseName`	string	Human-readable hangup cause (e.g. `Normal Hangup`).
`HangupCauseCode`	integer	Numeric hangup cause code (e.g. `4000`). See Hangup Causes.
`HangupSource`	string	Which party released the call - `Caller` or `Callee`.

Hangup Payload

{
  "Event": "Hangup",
  "CallUUID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "RequestID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Timestamp": "2026-03-18T12:00:08Z",
  "From": "+919876543210",
  "To": "+918012345678",
  "Direction": "outbound",
  "Status": "completed",
  "AccountId": "MA_XXXXXXXX",
  "TrunkID": "aabbccdd-1234-5678-90ab-cdef12345678",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "10.0.0.1",
  "SIPCallID": "abc123@10.0.0.1",
  "BridgeUUID": "bbccddee-2345-6789-01bc-def234567890",
  "Reason": "NORMAL_CLEARING",
  "StartTime": "2026-03-18T12:00:00Z",
  "EndTime": "2026-03-18T12:00:08Z",
  "Duration": 8,
  "Billsec": 3,
  "RingTime": 5,
  "Cost": 0.07,
  "Currency": "INR",
  "MOS": 4.5,
  "HangupCauseName": "Normal Hangup",
  "HangupCauseCode": 4000,
  "HangupSource": "Caller"
}

recording.completed

Fired when a call recording is ready, if recording is enabled on the trunk. The X-Vobiz-Event header is set to recording.completed. Unlike the call events, this payload uses snake_case field names.

Field	Type	Description
`event`	string	Always `recording.completed`.
`account_id`	string	Account identifier (`auth_id`) that owns the trunk.
`trunk_id`	string (UUID)	Trunk that carried the call.
`call_uuid`	string	Call identifier. Same value as `sip_call_id`.
`sip_call_id`	string	SIP Call-ID of the call. Matches `SIPCallID` in `CallInitiated` and `Hangup`.
`bridge_uuid`	string	UUID of the bridged (B-leg) call.
`recording_id`	string	Unique identifier for the recording.
`recording_url`	string	URL to download the recording.
`recording_format`	string	Audio format of the recording file.
`recording_duration_ms`	integer	Recording duration in milliseconds.
`recording_file_size`	integer	Recording file size in bytes.
`recording_channel`	string	Channel layout of the recording.
`from_number`	string	Caller number.
`to_number`	string	Called number.
`timestamp`	string (ISO 8601)	Time the event was generated.

recording.completed payload

{
  "event": "recording.completed",
  "account_id": "MA_XXXXXXXX",
  "trunk_id": "aabbccdd-1234-5678-90ab-cdef12345678",
  "call_uuid": "abc123@10.0.0.1",
  "sip_call_id": "abc123@10.0.0.1",
  "bridge_uuid": "bbccddee-2345-6789-01bc-def234567890",
  "recording_id": "RECORDING_ID",
  "recording_url": "https://RECORDING_URL",
  "recording_format": "RECORDING_FORMAT",
  "recording_duration_ms": 8000,
  "recording_file_size": 128000,
  "recording_channel": "RECORDING_CHANNEL",
  "from_number": "+919876543210",
  "to_number": "+918012345678",
  "timestamp": "2026-03-18T12:00:10Z"
}

HTTP request details

Headers sent with every webhook

Header	Value
`Content-Type`	application/json
`User-Agent`	Vobiz/1.0
`X-Vobiz-Event`	`CallInitiated`, `Hangup`, or `recording.completed`
`X-Vobiz-Request-ID`	Unique request identifier

Timeouts

Phase	Timeout
Call admission webhook (CallInitiated)	10 seconds
Hangup webhook - CDR to Vapor	5 seconds
Hangup webhook - Vapor to customer endpoint	10 seconds

Verify the request

Trunk webhooks are not currently signed. To verify a request came from Vobiz, allow-list the Vobiz callback IPs listed on IP Whitelisting, and use an unguessable path or token in your webhook URL.

Link events for the same call

Use SIPCallID to link CallInitiated and Hangup for the same call. In Hangup, CallUUID is Vobiz’s internal call ID and can differ from CallInitiated. X-Vobiz-Request-ID is unique per delivery; use it only to de-duplicate retries.

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.

​Configuration

​Security validation

​Webhook events

​CallInitiated

​Hangup

​recording.completed

​HTTP request details

​Headers sent with every webhook

​Timeouts

​Verify the request

​Link events for the same call

​Behavior & reliability

​Non-blocking

​Fail-open

​Informational only

Configuration

Security validation

Webhook events

CallInitiated

Hangup

recording.completed

HTTP request details

Headers sent with every webhook

Timeouts

Verify the request

Link events for the same call

Behavior & reliability

Non-blocking

Fail-open

Informational only