Skip to main content

Webhooks

Webhooks allow your application to receive real-time notifications about events happening in the Audian system. Instead of continuously polling the API for updates, webhooks push event data to your application's endpoint whenever an event occurs.

Base URL​

https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks

Authentication​

All requests require the X-Auth-Token header:

curl -X GET "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Accept: application/json"

How Webhooks Work​

When an event occurs in the Audian system:

  1. The system generates an event notification
  2. The notification is sent as an HTTP POST request to your configured endpoint
  3. Your endpoint receives the event data and processes it
  4. You return a 2xx status code to acknowledge receipt

List Webhooks​

curl -X GET "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks?paginate=false" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Accept: application/json"

Response​

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": [
    {
      "id": "webhook_abc123",
      "name": "Call Events",
      "uri": "https://yourapp.com/webhooks/audian",
      "hook": "channel_create",
      "enabled": true
    }
  ],
  "request_id": "req_xyz789",
  "status": "success"
}

Create Webhook​

curl -X PUT "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "name": "Call Events",
      "uri": "https://yourapp.com/webhooks/audian",
      "hook": "channel_create",
      "http_verb": "post",
      "retries": 3
    }
  }'

Update Webhook​

curl -X POST "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}" \
  -H "X-Auth-Token: {AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "enabled": true,
      "uri": "https://yourapp.com/webhooks/v2/audian"
    }
  }'

Delete Webhook​

curl -X DELETE "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}" \
  -H "X-Auth-Token: {AUTH_TOKEN}"

Webhook Event Types​

HookDescription
channel_createNew call started
channel_answerCall answered
channel_destroyCall ended
channel_bridgeCall connected to another party
object_createResource created
object_updateResource updated
object_deleteResource deleted

Webhook Fields​

FieldTypeDescription
idstringUnique webhook identifier
namestringWebhook display name
uristringYour endpoint URL
hookstringEvent type to subscribe
http_verbstringHTTP method (post, get)
retriesintegerNumber of retry attempts
enabledbooleanWhether webhook is active

Example Webhook Payload​

When an event occurs, Audian sends a POST request to your endpoint:

{
  "id": "evt_1234567890",
  "account_id": "account_abc123",
  "hook": "channel_destroy",
  "timestamp": "2026-02-04T10:30:00Z",
  "data": {
    "call_id": "call_xyz789",
    "caller_id_number": "+14155559999",
    "callee_id_number": "+14155552671",
    "duration_seconds": 245,
    "hangup_cause": "NORMAL_CLEARING"
  }
}

Retry Policy​

If your endpoint returns a non-2xx status code:

  1. Audian retries the webhook based on retries setting
  2. Retries use exponential backoff
  3. After all retries fail, the webhook is logged as failed

Best Practices​

  1. Return quickly: Acknowledge receipt within 5 seconds
  2. Process async: Handle heavy processing in background jobs
  3. Verify source: Validate requests come from Audian
  4. Handle duplicates: Design handlers to be idempotent
  5. Log everything: Keep logs for debugging

Test Webhooks​

Verify your endpoint is working:

curl -X POST "https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/webhooks/{WEBHOOK_ID}/test" \
  -H "X-Auth-Token: {AUTH_TOKEN}"

Topics​