Webhooks

Overview

Webhooks allow you to receive real-time notifications when calls complete. This enables you to integrate Call24x7.AI with your existing systems and workflows.

How Webhooks Work

You provide a webhook_url when making a call
Call24x7.AI processes the call
When the call completes, Call24x7.AI sends a POST request to your webhook URL
Your server processes the webhook data

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

Create an HTTP endpoint in your application that can receive POST requests:

app.post('/webhooks/call-complete', (req, res) => {
  const callData = req.body;
  
  // Process the call data
  console.log('Call completed:', callData.call_id);
  console.log('Status:', callData.status);
  console.log('Duration:', callData.duration_seconds);
  
  // Acknowledge receipt
  res.status(200).json({ received: true });
});

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/call-complete', methods=['POST'])
def handle_webhook():
    call_data = request.json
    
    # Process the call data
    print(f"Call completed: {call_data['call_id']}")
    print(f"Status: {call_data['status']}")
    print(f"Duration: {call_data['duration_seconds']}")
    
    # Acknowledge receipt
    return jsonify({'received': True}), 200

Step 2: Make Your Endpoint Publicly Accessible

Your webhook endpoint must be publicly accessible via HTTPS. For local development, use a tunneling service:

ngrok: ngrok http 3000
localtunnel: lt --port 3000
Cloudflare Tunnel: For production deployments

Step 3: Include Webhook URL in Call Requests

Add the webhook_url parameter when making calls:

curl -X POST https://api.call24x7.ai/outbound_call \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "to_phone_number": "+1234567890",
    "agent_id": "agent-123",
    "webhook_url": "https://your-app.com/webhooks/call-complete"
  }'

Webhook Payload

When a call completes, your webhook endpoint will receive a POST request with the following JSON payload:

{
  "call_id": "12345",
  "status": "COMPLETED",
  "call_direction": "outbound",
  "from_phone_number": "+1234567890",
  "to_phone_number": "+0987654321",
  "agent_id": "agent-123",
  "agent_name": "Customer Service Agent",
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:33:00Z",
  "start_time": "2024-01-15T10:30:05Z",
  "end_time": "2024-01-15T10:33:00Z",
  "duration_seconds": 175,
  "recording_url": "https://recordings.call24x7.ai/calls/12345.mp3",
  "summary": "Customer confirmed appointment for next week",
  "transcription": "Full conversation transcription...",
  "input_parameters": "{\"customer_id\": \"123\"}",
  "output_parameters": "{\"appointment_scheduled\": true, \"appointment_date\": \"2024-01-22\"}",
  "external_call_id": "order-12345",
  "cost": 0.44
}

Payload Fields

string

Unique identifier for the call

string

Final call status: COMPLETED, FAILED, or CANCELLED

string

Direction of the call: outbound or inbound

string

Phone number that initiated the call

string

Phone number that received the call

string

ID of the AI agent that handled the call

string

Name of the AI agent

number

Call duration in seconds

string

URL to access the call recording

string

Full conversation transcription

string

Structured data extracted from the conversation (JSON string)

number

Cost of the call in USD

Webhook Security

Verify Webhook Requests

While Call24x7.AI doesn’t currently sign webhooks, you should:

Use HTTPS: Always use HTTPS for webhook endpoints
Validate Source: Verify requests are coming from Call24x7.AI
Idempotency: Handle duplicate webhook deliveries gracefully
Timeouts: Respond quickly (within 5 seconds) to avoid retries

Example: Idempotent Webhook Handler

const processedCalls = new Set();

app.post('/webhooks/call-complete', async (req, res) => {
  const { call_id } = req.body;
  
  // Check if we've already processed this call
  if (processedCalls.has(call_id)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  
  // Process the webhook
  await processCallCompletion(req.body);
  
  // Mark as processed
  processedCalls.add(call_id);
  
  res.status(200).json({ received: true });
});

Webhook Retries

If your webhook endpoint doesn’t respond with a 2xx status code within 5 seconds, Call24x7.AI will retry the webhook:

Retry attempts: Up to 3 retries
Retry intervals: Exponential backoff (1s, 5s, 30s)
Timeout: 5 seconds per request

Always respond quickly to webhook requests to avoid unnecessary retries.

Testing Webhooks

Using ngrok for Local Testing

Start your local server: node server.js
Start ngrok: ngrok http 3000
Use the ngrok URL as your webhook URL: https://abc123.ngrok.io/webhooks/call-complete
Make a test call with the webhook URL

Using Webhook Testing Tools

webhook.site: Get a temporary webhook URL for testing
RequestBin: Create a bin to inspect webhook payloads
Postman: Use Postman’s webhook testing features

Best Practices

Idempotency: Handle duplicate webhook deliveries
Fast Response: Respond within 5 seconds
Error Handling: Log errors but return 200 to prevent retries
Validation: Validate webhook payload structure
Monitoring: Monitor webhook delivery success rates

Troubleshooting

Webhooks not being received

Verify your endpoint is publicly accessible
Check that the URL uses HTTPS
Ensure your server is running and accessible
Check firewall and security group settings

Webhooks timing out

Respond to webhooks quickly (within 5 seconds)
Process webhook data asynchronously if needed
Return 200 immediately, then process

Duplicate webhooks

Implement idempotency checks using call_id
Handle duplicate deliveries gracefully
Use a database to track processed webhooks

Examples

Update CRM After Call

app.post('/webhooks/call-complete', async (req, res) => {
  const { call_id, output_parameters, to_phone_number } = req.body;
  
  // Parse output parameters
  const data = JSON.parse(output_parameters || '{}');
  
  // Update CRM
  if (data.appointment_scheduled) {
    await crm.updateContact(to_phone_number, {
      lastCallDate: new Date(),
      appointmentScheduled: true,
      appointmentDate: data.appointment_date
    });
  }
  
  res.status(200).json({ received: true });
});

Send Notification

app.post('/webhooks/call-complete', async (req, res) => {
  const { call_id, status, duration_seconds } = req.body;
  
  if (status === 'COMPLETED') {
    await sendSlackNotification({
      text: `Call ${call_id} completed successfully`,
      duration: `${duration_seconds}s`
    });
  }
  
  res.status(200).json({ received: true });
});

Support

For webhook-related issues:

Check the API Reference for webhook configuration
Visit our Help Center
Contact support: support@call24x7.ai

Get Started

Essentials

Overview

How Webhooks Work

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

Step 2: Make Your Endpoint Publicly Accessible

Step 3: Include Webhook URL in Call Requests

Webhook Payload

Payload Fields

Webhook Security

Verify Webhook Requests

Example: Idempotent Webhook Handler

Webhook Retries

Testing Webhooks

Using ngrok for Local Testing

Using Webhook Testing Tools

Best Practices

Troubleshooting

Examples

Update CRM After Call

Send Notification

Support

​Overview

​How Webhooks Work

​Setting Up Webhooks

​Step 1: Create a Webhook Endpoint

​Step 2: Make Your Endpoint Publicly Accessible

​Step 3: Include Webhook URL in Call Requests

​Webhook Payload

​Payload Fields

​Webhook Security

​Verify Webhook Requests

​Example: Idempotent Webhook Handler

​Webhook Retries

​Testing Webhooks

​Using ngrok for Local Testing

​Using Webhook Testing Tools

​Best Practices

​Troubleshooting

​Examples

​Update CRM After Call

​Send Notification

​Support

Overview

How Webhooks Work

Setting Up Webhooks

Step 1: Create a Webhook Endpoint

Step 2: Make Your Endpoint Publicly Accessible

Step 3: Include Webhook URL in Call Requests

Webhook Payload

Payload Fields

Webhook Security

Verify Webhook Requests

Example: Idempotent Webhook Handler

Webhook Retries

Testing Webhooks

Using ngrok for Local Testing

Using Webhook Testing Tools

Best Practices

Troubleshooting

Examples

Update CRM After Call

Send Notification

Support