Setting Up Webhooks

Webhooks enable real-time integrations with external systems. Moreover, they automatically send data when events occur. In this guide, we’ll show you how to set up and use webhooks effectively.

[Screenshot: Webhook configuration page] Alt text: VoxPria webhook setup interface with URL and event configuration

What is a Webhook? #

A webhook is a way for VoxPria to send data to your external system automatically. Additionally, webhooks trigger in real-time when events happen.

How Webhooks Work: #

1. Event occurs in VoxPria (e.g., call ends)
2. VoxPria sends HTTP POST request to your URL
3. Your system receives the data
4. Your system processes and responds

Common Use Cases #

Webhooks are powerful for integrations. Furthermore, they enable countless automation scenarios:

• CRM Updates – Sync call data to Salesforce/HubSpot
• Database Recording – Store call records in your database
• Notifications – Alert your team via Slack/Discord
• Analytics – Send data to Google Analytics/Mixpanel
• Ticketing – Create support tickets from calls
• Custom Logic – Trigger your own business workflows

Prerequisites #

Before setting up webhooks, you’ll need:

• Endpoint URL – HTTPS URL where data will be sent
• Server Access – Ability to receive HTTP POST requests
• Basic Development Knowledge – Understanding JSON and APIs

Creating a Webhook #

Setting up webhooks is straightforward. Moreover, VoxPria handles all the complexity:

1. Go to FLOW AUTOMATION → Webhooks
2. Click “Create Webhook”
3. Configure webhook settings

[Screenshot: Webhook creation form with all fields] Alt text: VoxPria webhook creation showing name, URL, events, and authentication

Required Fields: #

• Name – Descriptive name (e.g., “Salesforce Sync”)
• URL – Your endpoint (must be HTTPS)
• Events – Which events trigger the webhook
• Authentication – Optional security headers

Available Events #

Choose which events should trigger your webhook. Additionally, you can select multiple events:

• call.started – When call begins
• call.answered – When call is picked up
• call.ended – When call completes
• call.failed – When call fails
• campaign.started – Campaign begins
• campaign.completed – Campaign finishes
• contact.created – New contact added
• contact.updated – Contact modified

Webhook Payload #

VoxPria sends JSON data in each webhook. Furthermore, the structure is consistent and well-documented:

Example Payload (call.ended): #

{
  "event": "call.ended",
  "timestamp": "2025-02-02T14:30:00Z",
  "data": {
    "call_id": "call_abc123",
    "campaign_id": "camp_xyz789",
    "contact_id": "cont_def456",
    "phone_number": "+15551234567",
    "status": "answered",
    "duration": 127,
    "recording_url": "https://...",
    "transcript": "...",
    "variables": {
      "appointment_confirmed": true,
      "appointment_date": "2025-02-10"
    }
  }
}

Authentication #

Secure your webhooks with authentication. Moreover, this prevents unauthorized access:

Authentication Methods: #

• API Key Header – Custom header with secret key
• Basic Auth – Username and password
• OAuth Token – Bearer token
• HMAC Signature – Cryptographic signature

Example: Add header Authorization: Bearer your_secret_key

Testing Webhooks #

Always test before activating. Additionally, VoxPria provides testing tools:

1. After creating webhook, click “Test Webhook”
2. VoxPria sends test payload to your URL
3. Check your endpoint received the data
4. Verify your system processed correctly
5. Fix any errors and retest

Monitoring Webhook Delivery #

Track webhook success and failures. Furthermore, logs help with debugging:

1. Go to FLOW AUTOMATION → Webhooks
2. Click on your webhook
3. View “Recent Deliveries”
4. See status codes and response times
5. Retry failed deliveries if needed

Status Codes: #

• 🟢 200-299: Success
• 🔴 400-499: Client error (check your endpoint)
• 🔴 500-599: Server error (your server issue)
• 🔴 Timeout: Response took >30 seconds

Error Handling #

VoxPria automatically retries failed webhooks. Moreover, the retry logic is intelligent:

• Retry Schedule: Immediate, 1min, 5min, 30min, 2hr, 12hr
• Max Attempts: 6 total attempts
• Exponential Backoff: Increasing delays between retries
• Manual Retry: You can retry manually anytime

Best Practices #

• ✅ Use HTTPS – Never use HTTP endpoints
• ✅ Respond Quickly – Process async, respond within 5 seconds
• ✅ Return 200 – Always return success status
• ✅ Validate Requests – Check authentication headers
• ✅ Handle Duplicates – Use call_id to prevent duplicate processing
• ✅ Log Everything – Keep logs of received webhooks
• ✅ Monitor Failures – Set up alerts for webhook errors

Learn more about webhooks and their technical implementation.

Related Articles:

• What is Flow Builder?
• Integrating with CRM Systems
• API Reference