WEBHOOKS GUIDE

Real-Time Event Notifications

Receive instant HTTP callbacks when calls complete, campaigns finish, or credits run low. Build responsive integrations that react to events in real-time[cite: 1, 62].

Real-Time

Event Delivery

HMAC

SHA256 Security

JSON

Payload Support

5x

Auto-Retries

How Webhooks Work

Subscribe to events, receive HTTP POST notifications when they occur[cite: 1, 68].

1

Create Webhook

Configure your endpoint URL and select which events to subscribe to via API or dashboard[cite: 1, 71].

2

Event Occurs

When a subscribed event happens (call ends, campaign completes), VoxPria triggers the webhook[cite: 1, 73].

3

Receive POST

Your endpoint receives an HTTP POST with the event payload and signature for verification[cite: 1, 75].

Supported Events

Event Name Description
call.completed Triggered when a phone call has finished and the summary/recording is ready.
campaign.completed Triggered when all contacts in a campaign have been processed.
credit.low Triggered when your account balance falls below the configured threshold.

Webhook Payload Examples


call.completed Event
application/json 
{
  "event": "call.completed",
  "timestamp": "2026-02-02T14:30:00Z",
  "data": {
    "id": "call_abc123xyz",
    "status": "completed",
    "phoneNumber": "+14155551234",
    "duration": 45,
    "summary": "Customer confirmed appointment for Feb 10 at 2pm"
  }
}

campaign.completed Event
application/json 
{
  "event": "campaign.completed",
  "timestamp": "2026-02-02T16:45:00Z",
  "data": {
    "id": "campaign_xyz789",
    "name": "Q1 Appointment Reminders",
    "stats": {
      "totalContacts": 500,
      "answered": 387,
      "voicemails": 62
    }
  }
}

credit.low Event
application/json 
{
  "event": "credit.low",
  "data": {
    "currentBalance": 12.50,
    "threshold": 15.00,
    "currency": "USD"
  }
}

🔐 Security & Verification

Every webhook includes an X-Webhook-Signature header. Verification steps:

  • Extract timestamp (t) and signature (v1) from the header.
  • Concatenate timestamp and raw body with a ‘.’.
  • Compute HMAC-SHA256 using your Webhook Secret.
  • Compare computed signature with the header signature.
# Verification Example Header
X-Webhook-Signature: t=1609459200,v1=6a295...

Retry Logic

If your server returns anything other than a 2xx status code, we retry delivery up to 5 times.

Attempt Delay After Previous
1st Retry 1 Minute
2nd Retry 5 Minutes
3rd Retry 30 Minutes
4th Retry 2 Hours
5th Retry 6 Hours

Webhook Best Practices

  • Use HTTPS: Only provide secure URLs to protect your data.
  • Idempotency: Design your system to handle the same event more than once safely.
  • Acknowledge Quickly: Return a 200 OK before processing long-running tasks.
  • Secret Rotation: Periodically rotate your webhook secrets for enhanced security.

Ready to Build with Webhooks?

Start receiving real-time event notifications in minutes.