Trunk Webhooks

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 (hangup with full details including duration, cost, and quality metrics).

Configure in the Console

Webhook 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

Two event types are delivered 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

Payload — allowed call:

JSON

{
  "Event": "CallInitiated",
  "CallUUID": "unique-call-id",
  "RequestID": "unique-request-id",
  "Timestamp": "2026-03-18T12:00:00Z",
  "From": "+917971542961",
  "To": "+918939894913",
  "Direction": "outbound",
  "Status": "initiated",
  "auth_id": "MA_ZRTEMCF7",
  "TrunkID": "trunk-uuid",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "103.x.x.x",
  "SIPCallID": "abc123@10.0.0.1",
  "Allowed": true,
  "Reason": ""
}

Payload — rejected call:

JSON

{
  "Event": "CallInitiated",
  "CallUUID": "unique-call-id",
  "RequestID": "unique-request-id",
  "Timestamp": "2026-03-18T12:00:00Z",
  "From": "+917971542961",
  "To": "+918939894913",
  "Direction": "outbound",
  "Status": "initiated",
  "auth_id": "MA_ZRTEMCF7",
  "TrunkID": "trunk-uuid",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "103.x.x.x",
  "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, and voice quality metrics (MOS score and jitter).

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).
Jitter	integer	Network jitter in milliseconds. Lower is better.

JSON

{
  "Event": "Hangup",
  "CallUUID": "unique-call-id",
  "RequestID": "unique-request-id",
  "Timestamp": "2026-03-18T12:05:00Z",
  "From": "+917971542961",
  "To": "+918939894913",
  "Direction": "outbound",
  "Status": "completed",
  "auth_id": "MA_ZRTEMCF7",
  "TrunkID": "trunk-uuid",
  "Domain": "1486467e.sip.vobiz.ai",
  "SourceIP": "103.x.x.x",
  "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

Header	Value
Content-Type	application/json
User-Agent	Vobiz-Vapor/1.0
X-Vobiz-Event	CallInitiated or Hangup
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

Behavior & Reliability

Non-blocking

All webhooks are sent asynchronously. The webhook request never delays 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.

Origination URI

Health & Monitoring