> ## Documentation Index
> Fetch the complete documentation index at: https://docs.recepta.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# 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 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
* **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:
```json theme={null}
{
"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": "+1234567890"
},
"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
```javascript theme={null}
// 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
```javascript theme={null}
// 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 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
* **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