TryVox

Webhooks

Receive real-time event notifications from TryVox.

Webhooks

Webhooks allow TryVox to send real-time HTTP notifications to your application when events occur, such as when a call is answered, ends, or when a message is delivered.

Overview

TryVox sends HTTP POST requests to your webhook URLs when events occur. Your application receives these requests, processes the event data, and responds accordingly.

Common Use Cases

  • Call control — Return VoxML instructions when a call is answered
  • Status tracking — Update your database when call status changes
  • Event logging — Log all call events for analytics and debugging
  • Error handling — Trigger alerts when calls fail

Webhook Configuration

Webhooks are configured in two ways:

1. Per-Call Webhooks

Specify webhook URLs when creating a call:

curl -X POST https://api.tryvox.io/v1/voice/accounts/$TRYVOX_AUTH_ID/calls \
  -u $TRYVOX_AUTH_ID:$TRYVOX_AUTH_TOKEN \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+919876543210",
    "to": "+14155551234",
    "answer_url": "https://your-app.com/answer",
    "ring_url": "https://your-app.com/ring",
    "hangup_url": "https://your-app.com/hangup",
    "fallback_url": "https://your-app.com/fallback",
    "status_callback_url": "https://your-app.com/status",
    "webhook_secret": "replace-with-your-account-webhook-secret"
  }'

Per-call webhook fields:

  • answer_url — Called when the call is answered. Returns VoxML to control the call.
  • ring_url — Called when the destination starts ringing.
  • hangup_url — Called when the call ends, with the full CDR.
  • fallback_url — Called if answer_url cannot be fetched successfully, such as a timeout or HTTP error.
  • status_callback_url — Called for ringing, answered, and hangup transitions.
  • webhook_secret — Your per-account signing secret for this call. It is accepted write-only and is never returned by the API.

2. Application-Level Webhooks

Configure default webhook URLs for many calls at once with a Voice Application. Application-level URLs are inherited by every phone number and SIP endpoint attached to it.

Voice Applications can store the same callback URLs and signing secret as defaults for inbound calls.

Verify voice webhook signatures

Signed POST requests to answer_url, fallback_url, ring_url, hangup_url, and status_callback_url include:

X-TryVox-Timestamp: 1785320611
X-TryVox-Signature: t=1785320611,v1=<hex-hmac-sha256>

Compute HMAC-SHA256(webhook_secret, "{X-TryVox-Timestamp}.{raw-request-body}"), compare the hexadecimal digest with v1 using a constant-time comparison, and reject timestamps outside your replay window (five minutes is recommended). Always verify the raw body bytes before parsing JSON.

For account-wide subscriptions to all call.* and message.* events, use Webhook Subscriptions instead.

Webhook payloads

Voice webhook payloads depend on the configured endpoint:

  • answer_url and fallback_url receive lower-case fields and must return VoxML.
  • ring_url, hangup_url, and status_callback_url receive Voice API fields such as Event, CallUUID, and Timestamp. Lifecycle status payloads also include RequestID.
  • Account-wide Webhook Subscriptions use their own event envelope; see Webhook Subscriptions.

Example: hangup URL payload

{
  "Event": "Hangup",
  "CallUUID": "c7a34e6f-9d1b-4c8e-a5f2-3b9d7e8c1a4f",
  "Timestamp": "2026-04-09T10:32:50.456Z",
  "From": "+919876543210",
  "To": "+14155551234",
  "Direction": "outbound",
  "Status": "completed",
  "AccountId": "AC123456",
  "Duration": 125,
  "Billsec": 120
}

Voice Webhooks (Answer URL)

The answer_url is special — it's called when a call is answered and expects a VoxML response to control the call.

Example Request to Your Answer URL

TryVox sends:

{
  "call_uuid": "c7a34e6f-9d1b-4c8e-a5f2-3b9d7e8c1a4f",
  "account_id": "AC123456",
  "from": "+919876543210",
  "to": "+14155551234",
  "direction": "outbound"
}

Example VoxML Response

Your server responds with:

{
  "voxml_version": "1.0",
  "instructions": [
    {
      "verb": "Say",
      "text": "Hello! I am your AI assistant. How can I help you today?",
      "engine": "google",
      "language": "en-US"
    },
    {
      "verb": "Stream",
      "url": "wss://your-app.com/ai-agent",
      "track": "inbound_track"
    }
  ]
}

TryVox executes these VoxML instructions to control the call flow.

Webhook Response Requirements

Your webhook endpoint should:

  1. Respond quickly — Return a response within 15 seconds
  2. Return 200 OK — Indicate successful receipt
  3. For answer_url — Return valid VoxML JSON

Example Webhook Handler (Node.js/Express)

app.post('/answer', (req, res) => {
  const { call_uuid, from, to } = req.body;

  console.log(`Call ${call_uuid} answered from ${from} to ${to}`);

  // Return VoxML to control the call
  res.json({
    voxml_version: "1.0",
    instructions: [
      {
        verb: "Say",
        text: "Welcome to our service!",
        engine: "google",
        language: "en-US"
      }
    ]
  });
});

app.post('/status', (req, res) => {
  const { Event, CallUUID, Status } = req.body;

  console.log(`Call ${CallUUID} ${Event}: ${Status}`);

  // Update your database, trigger alerts, etc.

  res.sendStatus(200);
});

Answer URL Fallback

If the answer_url times out or returns an HTTP error, TryVox tries the fallback_url once when configured:

{
  "answer_url": "https://your-app.com/answer",
  "fallback_url": "https://your-app.com/fallback"
}

Use the fallback URL to handle errors gracefully and prevent dropped calls.

Webhook Security

Verify Webhook Source

To ensure webhooks are coming from TryVox:

  1. Verify X-TryVox-Timestamp and X-TryVox-Signature
  2. Whitelist TryVox IP ranges in your firewall
  3. Use HTTPS for all webhook URLs

Use HTTPS

Always use HTTPS webhook URLs to prevent man-in-the-middle attacks:

✅ https://your-app.com/answer
❌ http://your-app.com/answer

Testing Webhooks Locally

Use tools like ngrok to expose your local server for webhook testing:

# Start ngrok tunnel
ngrok http 3000

# Use the ngrok URL in your webhook config
https://abc123.ngrok.io/answer

Debugging Webhooks

View Webhook Logs

The TryVox dashboard shows webhook request/response logs for each call:

  1. Go to Calls in the dashboard
  2. Click on a call to view details
  3. Scroll to Webhook Logs section

Common Issues

Webhook not called:

  • Check that the URL is publicly accessible
  • Verify HTTPS is used (not HTTP)
  • Check firewall rules

Webhook times out:

  • Ensure your endpoint responds within 15 seconds
  • Move slow operations (database writes, API calls) to background jobs

Invalid VoxML:

  • Validate your VoxML JSON structure
  • Check that all required fields are included
  • Use the VoxML validator

Next Steps

Error Handling

Understand TryVox API error responses and codes.

Voice API

Make and receive phone calls, stream audio, and control calls programmatically.

On this page

WebhooksOverviewCommon Use CasesWebhook Configuration1. Per-Call Webhooks2. Application-Level WebhooksVerify voice webhook signaturesWebhook payloadsExample: hangup URL payloadVoice Webhooks (Answer URL)Example Request to Your Answer URLExample VoxML ResponseWebhook Response RequirementsExample Webhook Handler (Node.js/Express)Answer URL FallbackWebhook SecurityVerify Webhook SourceUse HTTPSTesting Webhooks LocallyDebugging WebhooksView Webhook LogsCommon IssuesNext Steps