Webhooks

Configure webhooks for real-time event notifications and system integrations

Overview

Webhooks provide real-time notifications about events in your AI voice agent and chat system, allowing you to integrate with external systems and automate business processes.

Webhook Events

Call Events

Based on the platform implementation, webhooks can notify you about:

Call Lifecycle

• Call Started: When a call begins
• Call Ended: When a call completes
• Call Failed: When a call encounters errors
• Call Queued: When calls are waiting to be processed

Call Data

• Transcript Available: When call transcription is complete
• Recording Ready: When call recordings are processed
• Quality Score: When QA evaluation is completed
• Cost Calculated: When call costs are determined

Agent Events

• Agent Status Change: When agents go online/offline
• Configuration Update: When agent settings are modified
• Sync Status: When agent synchronization status changes
• Performance Alerts: When agents exceed performance thresholds

System Events

• Knowledge Base Update: When knowledge bases are modified
• Phone Number Changes: When number configurations change
• User Actions: When users perform significant actions
• System Maintenance: When system updates occur

Webhook Configuration

Setup Process

1. Endpoint Configuration: Specify your webhook URL endpoint
2. Event Selection: Choose which events to receive notifications for
3. Authentication: Configure security settings for webhook delivery
4. Testing: Verify webhook functionality with test events
5. Activation: Enable webhooks for live event notifications

Webhook URL Requirements

• HTTPS Required: Webhooks must use secure HTTPS endpoints
• Response Time: Endpoints should respond within 10 seconds
• Status Codes: Return appropriate HTTP status codes (200-299 for success)
• Reliability: Ensure endpoint availability for consistent delivery

Webhook Payload Structure

Standard Payload Format

Webhooks deliver JSON payloads with consistent structure:

{
  "event_type": "call.ended",
  "timestamp": "2024-01-15T10:30:00Z",
  "data": {
    "call_id": "call_12345",
    "status": "completed",
    "duration": 180,
    "cost": 0.25,
    "agent_id": "agent_67890",
    "phone_number": "[phone]"
  },
  "metadata": {
    "webhook_id": "webhook_abc123",
    "delivery_attempt": 1
  }
}

Event-Specific Data

Each event type includes relevant data:

• Call Events: Call ID, duration, cost, participants, status
• Agent Events: Agent ID, configuration changes, status updates
• System Events: Event details, affected resources, timestamps
• User Events: User ID, action performed, resource affected

Security and Authentication

Webhook Security

• Signature Verification: Verify webhook authenticity using signatures
• IP Whitelisting: Restrict webhook sources to known IP addresses
• HTTPS Encryption: All webhook data transmitted securely
• Payload Validation: Validate incoming webhook data structure

Authentication Methods

• API Keys: Include API keys in webhook headers
• HMAC Signatures: Cryptographic signatures for payload verification
• Basic Authentication: Username/password authentication
• Bearer Tokens: JWT or similar token-based authentication

Retry and Reliability

Delivery Guarantees

• Retry Logic: Automatic retries for failed deliveries
• Exponential Backoff: Increasing delays between retry attempts
• Maximum Attempts: Configurable maximum retry attempts
• Dead Letter Queue: Store failed webhooks for manual review

Monitoring and Logging

• Delivery Status: Track successful and failed webhook deliveries
• Response Logging: Log endpoint responses and error messages
• Performance Metrics: Monitor webhook delivery performance
• Alert System: Notifications for webhook delivery failures

Integration Examples

CRM Integration

// Example webhook handler for CRM integration
app.post('/webhook/call-ended', (req, res) => {
  const { event_type, data } = req.body;
  
  if (event_type === 'call.ended') {
    // Update CRM with call information
    crm.updateContact(data.caller_id, {
      last_call_date: data.timestamp,
      call_duration: data.duration,
      call_outcome: data.status
    });
  }
  
  res.status(200).send('OK');
});

Notification System

// Example webhook handler for notifications
app.post('/webhook/notifications', (req, res) => {
  const { event_type, data } = req.body;
  
  switch (event_type) {
    case 'call.failed':
      notificationService.sendAlert('Call Failed', data);
      break;
    case 'agent.offline':
      notificationService.sendWarning('Agent Offline', data);
      break;
  }
  
  res.status(200).send('OK');
});

Use Cases

Business Automation

Lead Management

• Lead Capture: Automatically add new leads to CRM
• Follow-up Scheduling: Schedule automatic follow-up tasks
• Lead Scoring: Update lead scores based on call quality
• Assignment Rules: Route leads to appropriate sales reps

Customer Service

• Ticket Creation: Create support tickets for failed calls
• Escalation Rules: Escalate high-priority issues
• Customer Updates: Notify customers of call outcomes
• Service Metrics: Track service quality metrics

Analytics and Reporting

• Real-time Dashboards: Update business dashboards with live data
• Custom Reports: Generate reports based on webhook data
• Data Warehousing: Store webhook data in data warehouses
• Business Intelligence: Feed data into BI systems for analysis

Webhook Management

Configuration Interface

The platform provides tools for:

• Webhook Creation: Set up new webhook endpoints
• Event Configuration: Select which events trigger webhooks
• Security Settings: Configure authentication and security
• Testing Tools: Test webhook functionality with sample data

Monitoring Dashboard

• Delivery Status: View webhook delivery success/failure rates
• Event History: Review recent webhook events and deliveries
• Performance Metrics: Monitor webhook performance and reliability
• Error Analysis: Identify and troubleshoot webhook issues

Best Practices

Implementation Guidelines

1. Idempotency: Handle duplicate webhook deliveries gracefully
2. Quick Processing: Process webhooks quickly to avoid timeouts
3. Error Handling: Implement robust error handling and logging
4. Security: Always validate webhook authenticity and data
5. Monitoring: Set up monitoring and alerting for webhook failures

Performance Optimization

• Async Processing: Process webhook data asynchronously when possible
• Batching: Batch process multiple webhooks to improve efficiency
• Caching: Cache frequently accessed data to reduce processing time
• Rate Limiting: Implement rate limiting to handle webhook volume
• Resource Management: Monitor and manage server resources

Troubleshooting

Common Issues

• Delivery Failures: Check endpoint availability and response codes
• Authentication Errors: Verify security configuration and credentials
• Timeout Issues: Ensure endpoints respond quickly enough
• Data Validation: Confirm webhook payload structure and content

Debugging Tools

• Webhook Logs: Review detailed delivery logs and error messages
• Test Events: Send test webhooks to verify configuration
• Payload Inspector: Examine webhook payload structure and data
• Network Tools: Use network tools to diagnose connectivity issues