Webhooks

Receive real-time notifications when events occur in your Vagary Voice account.

Overview

Webhooks allow your application to receive HTTP callbacks when specific events happen, such as:

• A conversation starts or ends
• Speech is transcribed
• An error occurs

Setting Up Webhooks

Via Dashboard

1. Go to Settings → Webhooks
2. Click Add Webhook
3. Enter your endpoint URL
4. Select the events you want to receive
5. Save the webhook

Via API

curl -X POST https://api.vagaryvoice.cloud/v1/webhooks \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.com/webhook",
    "events": ["conversation.started", "conversation.ended", "transcript.ready"],
    "secret": "your_webhook_secret"
  }'

Event Types

Event	Description
conversation.started	A new conversation began
conversation.ended	A conversation completed
conversation.error	An error occurred
transcript.ready	Transcript is available
speech.interim	Interim transcription
speech.final	Final transcription
bot.message	Bot sent a response

Webhook Payload

{
  "event": "conversation.ended",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "conversation_id": "conv_abc123",
    "bot_id": "bot_xyz789",
    "duration_seconds": 120,
    "transcript": [...],
    "metadata": {}
  },
  "signature": "sha256=..."
}

Verifying Signatures

Always verify webhook signatures to ensure authenticity:

const crypto = require('crypto');

function verifySignature(payload, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  return signature === `sha256=${expected}`;
}

Retry Policy

Failed webhook deliveries are retried:

• 1st retry: 1 minute
• 2nd retry: 5 minutes
• 3rd retry: 30 minutes
• 4th retry: 2 hours
• 5th retry: 24 hours

After 5 failed attempts, the webhook is disabled.

Best Practices

1. Return 2xx quickly - Process asynchronously
2. Verify signatures - Prevent spoofing
3. Handle duplicates - Use idempotency keys
4. Monitor failures - Check webhook logs in dashboard