Webhooks
Subscribe to call, SMS, fax, and object-mutation events. Configure URI, HTTP verb, body format, and retry count per subscription.
Webhooks let your service receive HTTP requests when events happen in Vinix — new calls, calls answered, calls finished, SMS, faxes, and object mutations (account / callflow / device / user / etc.).
The full reference is at Core API → Messaging → Webhooks.
Subscribe
Create a subscription by POSTing a webhook document:
curl -X PUT https://api.vinixglobal.com/v2/accounts/$ACCOUNT_ID/webhooks \
-H "X-Auth-Token: $VINIX_AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"data": {
"name": "completed-calls",
"uri": "https://example.com/vinix/hooks",
"hook": "channel_destroy",
"http_verb": "post",
"format": "json",
"retries": 2
}
}'| Field | Required | Notes |
|---|---|---|
name | yes | Friendly name shown in the dashboard |
uri | yes | Your endpoint |
hook | yes | One of the available hook IDs (see below) |
http_verb | no — default post | get, post, or put |
format | no — default form-data | form-data or json |
retries | no — default 2 | Retry the request this many times on failure |
enabled | no — default true | Toggle without deleting |
include_subaccounts | no — default false | Forward sub-account events too |
custom_data | no | Properties merged into every payload |
Available hooks
Query the system for what's available right now:
curl https://api.vinixglobal.com/v2/webhooks \
-H "X-Auth-Token: $VINIX_AUTH_TOKEN"The currently-advertised hook IDs:
| Hook ID | Fires when |
|---|---|
channel_create | A call leg starts (CHANNEL_CREATE) |
channel_answer | A call leg answers |
channel_destroy | A call leg ends |
channel_bridge | Two legs bridge |
sms | SMS is created (coming soon — pairs with the SMS send/receive API) |
notifications | A notifications event (voicemail, fax, ports, etc.) is published — modifiers select which type |
fax | Fax status or object change |
object | An object document changes — modifiers pick action (doc_created / doc_edited / doc_deleted) and type (account, callflow, device, faxbox, media, user, vmbox, fax, mailbox_message, call_recording) |
The list returned by GET /v2/webhooks is the source of truth — it may
expand as the platform evolves.
Payload format
When format is form-data (default) the body is URL-encoded form
data. When format is json the body is a JSON object. Exact fields
depend on the hook.
Retries
If your endpoint returns a non-2xx response or times out, Vinix retries
up to retries times (default 2). Backoff is set by the platform; it's
not configurable per-subscription.
Disabling on repeated failure
After sustained failures the platform can disable a webhook and emit
an attempts log at /accounts/{id}/webhooks/{webhook_id}/attempts.
Re-enable via PATCH /accounts/{id}/webhooks/{webhook_id} with
{ enabled: true }.
Signature verification is not built into the webhook surface
today. If you need HMAC, mTLS, or an IP allowlist for inbound
webhook authenticity, that's not currently shipped — use
custom_data plus a long secret in the URI as a stopgap, and reach
out to
[email protected]
if signing is a hard requirement for your integration.