Campaign Webhooks

Overview

Vaani provides two types of webhooks for campaign monitoring:

Campaign-Level Webhooks - Triggered on campaign lifecycle events (started, paused, resumed, completed, report ready)
Per-Call Webhooks - Triggered after each call completes post-processing

Webhooks are delivered once (10 second timeout) and are not retried. If your endpoint is down or returns an error, that event is lost. Webhooks set through the API via campaign_webhook_url / per_call_webhook_url are also not signed (see Webhook Security). Use Get Campaign Status and Get Campaign Results to reconcile anything you miss.

Campaign-Level Webhooks

Notifies you when a campaign changes state.

Configuration

Provide campaign_webhook_url when creating or updating a campaign:

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

Payload

{
  "event": "campaign_paused",
  "campaign_id": "abc-123-xyz",
  "campaign_name": "Summer Promo 2024",
  "campaign_status": "paused",
  "timestamp": "2026-07-01T14:30:00.123456"
}

Field	Description
`event`	Event name, see Event Types Reference
`campaign_id`	Campaign UUID
`campaign_name`	Campaign name
`campaign_status`	Status of the campaign at the time of the event
`timestamp`	UTC time of the event, ISO 8601. This one has no timezone suffix (naive UTC)

The campaign_report_ready event is sent once the results file has been generated and adds three fields:

{
  "event": "campaign_report_ready",
  "campaign_id": "abc-123-xyz",
  "campaign_name": "Summer Promo 2024",
  "campaign_status": "completed",
  "timestamp": "2026-07-01T18:02:11.482913",
  "results_url": "https://...presigned-url...",
  "total_contacts": 1000,
  "total_results": 1000
}

results_url is a pre-signed download link that is valid for 24 hours.

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.vaanivoice.ai/api/campaigns/create" \
  -H "X-API-Key: vaani_abc123..." \
  -F "per_call_webhook_url=https://your-domain.com/webhooks/call"

Payload

{
  "event": "call_postprocessing",
  "call_id": "outbound-1785148654-d915171f",
  "campaign_id": "d079211d-7519-4441-988c-368ed9c90812",
  "campaign_name": "Test Campaign",
  "timestamp": "2026-07-27T10:38:36.588135+00:00",
  "data": {
    "room_name": "outbound-1785148654-d915171f",
    "call_id": "outbound-1785148654-d915171f",
    "call_duration": 21.65,
    "end_reason": "Call ended",
    "summary": "The agent greeted the customer and offered assistance after detecting inactivity. The customer did not respond, so no issue was identified or addressed. No next steps were established due to lack of engagement.",
    "entities": null,
    "dispositions": null,
    "recording_url": "https://mohammad-bk.vaaniresearch.com/api/stream/outbound-1785148654-d915171f",
    "transcript": "[10:37:59] AGENT: Hi! you have reached our customer service, I am your assistant, how can I help you today?\n\n[10:38:08] AGENT: Hello, you have been inactive for a while, Please let me know if you need help,"
  }
}

call_duration is in seconds (a float, rounded to 2 decimals). transcript and summary are inside data, not at the top level. transcript is a plain-text string (or null).

call_postprocessing is not sent for calls that were too short, had no transcript, where the contact never spoke, or that never connected (no answer, rejected, failed). Such contacts still appear in the campaign results file. recording_url is a signed link ending in ?token=....

Delivery

	Behaviour
Method	`POST` with a JSON body and `Content-Type: application/json`
Attempts	1. There is no retry on a non-2xx response, a timeout or a connection error
Timeout	10 seconds
Ordering	Not guaranteed

Make your endpoint idempotent (key on call_id, or on campaign_id + event) and respond with a 2xx quickly.

Webhook Security

When a webhook has a signing secret, Vaani adds one header:

X-Webhook-Signature: sha256=<hex digest>

The digest is HMAC-SHA256(secret, raw request body), hex encoded. There is no timestamp header and the timestamp is not part of the signed string.

A signature is only sent when the webhook has a secret. Webhooks supplied through the API with campaign_webhook_url or per_call_webhook_url have no secret, so those requests arrive unsigned. Do not reject requests that lack the header unless you have configured a secret for that webhook in the dashboard. Restrict your endpoint by an unguessable URL path or token query parameter instead.

Python Verification Example:

import hmac
import hashlib

def verify_webhook(raw_body: bytes, signature_header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(
        secret.encode(), raw_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature_header or "")

Always compute the HMAC over the raw bytes you received, before JSON parsing.

Webhook Endpoint Requirements

Your webhook endpoint must:

Respond quickly (< 10 seconds, ideally < 2) or the delivery is abandoned
Return 2xx status to acknowledge receipt
Be publicly accessible over HTTPS
Handle duplicate or missing events (there are no retries; reconcile with the status/results endpoints)

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 only if you configured a secret for this webhook
    signature = request.headers.get('X-Webhook-Signature')
    if signature and not verify_webhook(request.data, signature, YOUR_SECRET):
        return jsonify({"error": "Invalid signature"}), 401

    event = payload['event']
    if event.startswith('campaign_'):
        print(f"Campaign {payload['campaign_id']} -> {event} ({payload['campaign_status']})")
    elif event == 'call_postprocessing':
        data = payload['data']
        print(f"Call {payload['call_id']} lasted {data['call_duration']}s")
        print(data['summary'])

    return jsonify({"status": "received"}), 200

Event Types Reference

Campaign Events

Event	Sent when
`campaign_started`	A scheduled or newly populated campaign starts dialling
`campaign_resumed`	A paused (or otherwise inactive) campaign is set back to `active`
`campaign_paused`	The campaign is paused, manually, by the schedule/calling window, or automatically (for example when you update it)
`campaign_completed`	The campaign completed (all contacts processed) or you stopped it
`campaign_report_ready`	The results file is ready to download. Also sent after you pause, stop or cancel a campaign, because the file is regenerated each time

There is no event for cancellation. /cancel sends only a campaign_report_ready event. campaign_paused is sent only when the status actually changes, so pausing an already paused campaign sends nothing.

Call Events

Event	Sent when
`call_postprocessing`	A call finished and its transcript, summary, entities and dispositions are ready. This is the only per-call event delivered to `per_call_webhook_url`

Other call-lifecycle events (call_started, call_ended, call_failed, call_no_answer, …) exist for webhooks configured in the dashboard, but they are not sent to the URLs you pass in the campaign API. Names with a dot (campaign.status_changed, call.completed) do not exist.

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.vaanivoice.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 quickly (the 10 second timeout is not retried)
Remember that only the events listed above are sent to the campaign API URLs

Receiving duplicate events

A state can legitimately fire the same event more than once (for example repeated campaign_paused)
Key on call_id for call_postprocessing
Return 200 for duplicates

Webhook timing out

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

Overview

Campaigns

Agents

Calls

Campaign Webhooks

Overview

Campaign-Level Webhooks

Configuration

Payload

Per-Call Webhooks

Configuration

Payload

Delivery

Webhook Security

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

​Delivery

​Webhook Security

​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

Delivery

Webhook Security

Webhook Endpoint Requirements

Example Flask Endpoint

Event Types Reference

Campaign Events

Call Events

Testing Webhooks

Common Issues