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/{auth_id}/calls \
  -H "Authorization: Bearer tvx_sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "from": "+919876543210",
    "to": "+14155551234",
    "answer_url": "https://your-app.com/answer",
    "hangup_url": "https://your-app.com/hangup",
    "ring_url": "https://your-app.com/ring",
    "status_callback_url": "https://your-app.com/status"
  }'

Webhook URLs:

answer_url — Called when the call is answered (return VoxML to control the call)
hangup_url — Called when the call ends
ring_url — Called when the call starts ringing
status_callback_url — Called for all status changes (queued, ringing, answered, ended)

2. Application-Level Webhooks

Configure default webhook URLs for all calls in your Application Settings.

Per-call webhooks override application-level webhooks.

Webhook Payloads

All webhook requests include a JSON payload with event details.

Example: Call Answered Event

{
  "event": "call.answered",
  "call_uuid": "c7a34e6f-9d1b-4c8e-a5f2-3b9d7e8c1a4f",
  "account_id": "AC123456",
  "from": "+919876543210",
  "to": "+14155551234",
  "direction": "outbound",
  "status": "answered",
  "timestamp": "2026-04-09T10:30:45.123Z"
}

Example: Call Ended Event

{
  "event": "call.ended",
  "call_uuid": "c7a34e6f-9d1b-4c8e-a5f2-3b9d7e8c1a4f",
  "account_id": "AC123456",
  "from": "+919876543210",
  "to": "+14155551234",
  "direction": "outbound",
  "status": "completed",
  "duration": 125,
  "end_reason": "hangup",
  "timestamp": "2026-04-09T10:32:50.456Z"
}

Common Payload Fields

event — Event type (e.g., call.answered, call.ended)
call_uuid — Unique identifier for the call
account_id — Your TryVox account ID
from — Caller's phone number
to — Recipient's phone number
direction — inbound or outbound
status — Current call status
timestamp — ISO 8601 timestamp of when the event occurred

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:

{
  "event": "call.answered",
  "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:

Respond quickly — Return a response within 5 seconds
Return 200 OK — Indicate successful receipt
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, call_uuid, status } = req.body;

  console.log(`Call ${call_uuid} status: ${status}`);

  // Update your database, trigger alerts, etc.

  res.sendStatus(200);
});

Webhook Retries

If your webhook endpoint fails or doesn't respond, TryVox automatically retries:

Retry attempts: Up to 3 times
Retry strategy: Exponential backoff (1s, 4s, 16s)
Timeout: 5 seconds per attempt

Answer URL Fallback

If the answer_url fails after all retries, TryVox tries the fallback_url (if 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:

Check the signature header (coming soon)
Whitelist TryVox IP ranges in your firewall
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:

Go to Calls in the dashboard
Click on a call to view details
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 5 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

Learn VoxML to control calls with voice markup
Explore Voice API for making and managing calls
Set up Verify API for OTP verification

Webhooks

On this page