Campaign Webhooks

Overview

Vaani provides two types of webhooks for campaign monitoring:

Campaign-Level Webhooks — Triggered on campaign status changes
Per-Call Webhooks — Triggered after each call completes post-processing

Campaign-Level Webhooks

Notifies you when campaign status changes (active, paused, completed, cancelled).

Configuration

Provide campaign_webhook_url when creating or updating a campaign:

curl -X POST "https://api.vaani.ai/api/campaigns/create" \
  -H "X-API-Key: vaani_abc123..." \
  -F "campaign_webhook_url=https://your-domain.com/webhooks/campaign"

Payload

{
  "event": "campaign.status_changed",
  "campaign_id": "abc-123-xyz",
  "campaign_name": "Summer Promo 2024",
  "old_status": "active",
  "new_status": "paused",
  "timestamp": "2026-07-01T14:30:00Z",
  "stats": {
    "total_calls": 523,
    "completed": 498,
    "pending": 477,
    "in_progress": 3,
    "failed": 12
  }
}

Per-Call Webhooks

Notifies you after each call completes and transcript/summary are generated.

Configuration

Provide per_call_webhook_url when creating or updating a campaign:

curl -X POST "https://api.vaani.ai/api/campaigns/create" \
  -H "X-API-Key: vaani_abc123..." \
  -F "per_call_webhook_url=https://your-domain.com/webhooks/call"

Payload

{
  "event": "call.completed",
  "call_id": "call-789-xyz",
  "campaign_id": "abc-123-xyz",
  "campaign_name": "Summer Promo 2024",
  "contact": {
    "name": "John Doe",
    "phone": "+919876543210"
  },
  "call_status": "completed",
  "call_duration_seconds": 87,
  "call_outcome": "interested",
  "call_tags": ["qualified", "follow_up_needed"],
  "transcript": "Agent: Hello, this is...\nCustomer: Hi...",
  "summary": "Customer expressed interest in the product...",
  "timestamp": "2026-07-01T14:35:22Z"
}

Webhook Retry Logic

If your webhook endpoint is unreachable or returns a non-2xx status, Vaani automatically retries with exponential backoff:

Attempt	Delay
1	Immediate
2	5 seconds
3	25 seconds
4	125 seconds (~2 min)
5	625 seconds (~10 min)

After 5 failed attempts, the webhook is marked as failed and no further retries occur.

Webhook Security

Verify Webhook Signature

Vaani signs all webhook payloads with HMAC-SHA256. Verify the signature before processing: Request Headers:

X-Vaani-Signature: sha256=abc123...
X-Vaani-Timestamp: 1719842400

Python Verification Example:

import hmac
import hashlib

def verify_webhook(payload: bytes, signature: str, secret: str, timestamp: str):
    # Prevent replay attacks (check timestamp is within 5 minutes)
    if abs(int(time.time()) - int(timestamp)) > 300:
        return False
    
    # Compute expected signature
    expected = hmac.new(
        secret.encode(),
        f"{timestamp}.{payload.decode()}".encode(),
        hashlib.sha256
    ).hexdigest()
    
    # Compare signatures securely
    return hmac.compare_digest(f"sha256={expected}", signature)

Always verify webhook signatures in production to prevent spoofing attacks.

Webhook Endpoint Requirements

Your webhook endpoint must:

Respond quickly (< 5 seconds) to avoid timeouts
Return 2xx status to acknowledge receipt
Be publicly accessible over HTTPS
Handle duplicate events (use event IDs for idempotency)

Example Flask Endpoint

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/campaign', methods=['POST'])
def campaign_webhook():
    payload = request.get_json()
    
    # Verify signature (recommended)
    signature = request.headers.get('X-Vaani-Signature')
    timestamp = request.headers.get('X-Vaani-Timestamp')
    if not verify_webhook(request.data, signature, YOUR_SECRET, timestamp):
        return jsonify({"error": "Invalid signature"}), 401
    
    # Process event
    if payload['event'] == 'campaign.status_changed':
        campaign_id = payload['campaign_id']
        new_status = payload['new_status']
        print(f"Campaign {campaign_id} changed to {new_status}")
    
    return jsonify({"status": "received"}), 200

Event Types Reference

Campaign Events

Event	Description
`campaign.status_changed`	Campaign status changed
`campaign.completed`	All calls finished
`campaign.cancelled`	Campaign was cancelled

Call Events

Event	Description
`call.completed`	Call finished and processed
`call.failed`	Call attempt failed
`call.no_answer`	Recipient didn’t answer

Testing Webhooks

Use tools like webhook.site or ngrok to test webhooks locally:

# 1. Start ngrok tunnel
ngrok http 5000

# 2. Use the ngrok URL in your campaign
curl -X POST "https://api.vaani.ai/api/campaigns/create" \
  -F "campaign_webhook_url=https://abc123.ngrok.io/webhooks/campaign"

Common Issues

Webhook not receiving events

Ensure URL is publicly accessible over HTTPS
Check firewall/security group rules
Verify endpoint returns 2xx status
Check Vaani logs for delivery attempts

Receiving duplicate events

Implement idempotency using event IDs
Store processed event IDs in database
Return 200 for duplicate events

Webhook timing out

Process events asynchronously (queue-based)
Respond with 200 immediately, then process
Keep endpoint response time < 5 seconds

Overview

Campaigns

Agents

Calls

Overview

Campaign-Level Webhooks

Configuration

Payload

Per-Call Webhooks

Configuration

Payload

Webhook Retry Logic

Webhook Security

Verify Webhook Signature

Webhook Endpoint Requirements

Example Flask Endpoint

Event Types Reference

Campaign Events

Call Events

Testing Webhooks

Common Issues

​Overview

​Campaign-Level Webhooks

​Configuration

​Payload

​Per-Call Webhooks

​Configuration

​Payload

​Webhook Retry Logic

​Webhook Security

​Verify Webhook Signature

​Webhook Endpoint Requirements

​Example Flask Endpoint

​Event Types Reference

​Campaign Events

​Call Events

​Testing Webhooks

​Common Issues

Overview

Campaign-Level Webhooks

Configuration

Payload

Per-Call Webhooks

Configuration

Payload

Webhook Retry Logic

Webhook Security

Verify Webhook Signature

Webhook Endpoint Requirements

Example Flask Endpoint

Event Types Reference

Campaign Events

Call Events

Testing Webhooks

Common Issues