Skip to main content

🔗 Webhooks

Webhooks enable real-time communication between AI Sync and external systems by sending HTTP POST requests when specific events occur in your system.

🎯 Overview

Webhooks provide instant notifications about important events in your AI Sync system, allowing you to build powerful integrations and automated workflows. Webhook Overview

Real-time Notifications

Receive instant updates when events occur in your system

External Integrations

Connect with CRMs, databases, and third-party applications

Automated Workflows

Trigger actions in external systems based on AI Sync events

Data Synchronization

Keep external systems in sync with your AI Sync data

🔄 Webhook Workflow

1

Event Occurs

An action happens in AI Sync (call ends, agent responds, etc.)
2

Webhook Triggered

System identifies configured webhooks for the event type
3

HTTP Request Sent

POST request with event data sent to your endpoint URL
4

Response Processed

Your system processes the data and sends acknowledgment
5

Retry Logic

Failed requests are retried with exponential backoff

📋 Webhook Management

Navigate to Setup > Webhooks to manage your webhook configurations. Webhook Management

Webhook Table Overview

ColumnDescriptionExample
#Sequential webhook ID1, 2, 3
TitleWebhook name/identifierCRM Integration, Analytics Sync
HitsTotal number of webhook calls1,247
Last HitMost recent webhook execution2025-01-15 14:30:25
Created AtWebhook creation timestamp2025-01-10 10:40 PM
ActionManagement optionsEdit, Delete, View Endpoints

Quick Actions

Add New Webhook

Create new webhook endpoints for your integrations

Edit Configuration

Modify existing webhook settings and URLs

View Endpoints

Monitor webhook performance and delivery status

🎛️ Webhook Configuration

Creating a New Webhook

1

Click Add Webhook

Navigate to Setup > Webhooks and click the “Add” button
2

Configure Basic Settings

  • Title: Descriptive name for the webhook
  • URL: Your endpoint URL to receive webhook data
  • Method: HTTP method (typically POST)
3

Select Event Types

Choose which events should trigger this webhook
4

Configure Authentication

Set up security headers and authentication tokens
5

Test and Activate

Test the webhook and activate it for live events
Webhook Configuration

Authentication & Security

Authorization: Bearer your-api-key-here
X-API-Key: your-secret-key
// Verify webhook signature
const signature = req.headers['x-webhook-signature'];
const payload = JSON.stringify(req.body);
const expectedSignature = crypto
  .createHmac('sha256', webhookSecret)
  .update(payload)
  .digest('hex');
AI Sync Webhook IPs:
  • 192.168.1.100
  • 192.168.1.101
  • 192.168.1.102

🎪 Available Webhook Events

📞 Call Events

Call Started

Event: call.startedTriggered: When a call beginsUse Cases: Call logging, real-time monitoring

Call Ended

Event: call.endedTriggered: When a call completesUse Cases: Call analytics, CRM updates

Call Answered

Event: call.answeredTriggered: When a call is answeredUse Cases: Connection tracking, response rates

Call Transferred

Event: call.transferredTriggered: When a call is transferredUse Cases: Transfer logging, agent routing

🤖 Agent Events

Agent Created

Event: agent.createdTriggered: When a new AI agent is createdUse Cases: Inventory management, provisioning

Agent Updated

Event: agent.updatedTriggered: When agent configuration changesUse Cases: Configuration sync, audit trails

Agent Status Changed

Event: agent.status_changedTriggered: When agent goes online/offlineUse Cases: Availability tracking, monitoring

Agent Performance

Event: agent.performanceTriggered: Performance threshold eventsUse Cases: Quality monitoring, alerts

📊 Campaign Events

Campaign Started

Event: campaign.startedTriggered: When a campaign beginsUse Cases: Campaign tracking, notifications

Campaign Completed

Event: campaign.completedTriggered: When a campaign finishesUse Cases: Results processing, reporting

Lead Generated

Event: lead.generatedTriggered: When a new lead is createdUse Cases: CRM integration, lead routing

Appointment Scheduled

Event: appointment.scheduledTriggered: When an appointment is bookedUse Cases: Calendar sync, confirmations

💬 SMS Events

SMS Sent

Event: sms.sentTriggered: When an SMS is deliveredUse Cases: Delivery tracking, billing

SMS Received

Event: sms.receivedTriggered: When an SMS is receivedUse Cases: Response handling, conversations

SMS Failed

Event: sms.failedTriggered: When SMS delivery failsUse Cases: Error handling, retry logic

SMS Replied

Event: sms.repliedTriggered: When recipient replies to SMSUse Cases: Conversation tracking, engagement

📦 Webhook Payload Structure

Standard Payload Format

All webhooks follow a consistent JSON structure:
{
  "event": "call.ended",
  "timestamp": "2025-01-15T14:30:25.123Z",
  "webhook_id": "wh_123456789",
  "data": {
    // Event-specific data
  },
  "metadata": {
    "version": "1.0",
    "signature": "sha256=abc123..."
  }
}

Call Event Payload Example

{
  "event": "call.ended",
  "timestamp": "2025-01-15T14:30:25.123Z",
  "webhook_id": "wh_123456789",
  "data": {
    "call_id": "call_987654321",
    "agent_id": "agent_abc123",
    "caller_number": "+1234567890",
    "called_number": "+0987654321",
    "call_duration": 180,
    "call_status": "completed",
    "call_direction": "outbound",
    "recording_url": "https://recordings.ai-sync.com/call_987654321.mp3",
    "transcription": "Hello, this is John calling about...",
    "sentiment": "positive",
    "disposition": "interested",
    "tags": ["qualified", "follow-up"],
    "custom_fields": {
      "lead_score": 85,
      "next_action": "schedule_demo"
    }
  },
  "metadata": {
    "version": "1.0",
    "signature": "sha256=abc123def456..."
  }
}

🔒 Security Best Practices

Webhook Verification

Always verify webhook signatures to ensure authenticity:
const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature, 'hex'),
    Buffer.from(expectedSignature, 'hex')
  );
}

// Middleware to verify webhooks
app.use('/webhook/*', (req, res, next) => {
  const signature = req.headers['x-webhook-signature'];
  const payload = JSON.stringify(req.body);
  
  if (!verifyWebhookSignature(payload, signature, WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  next();
});
Implement rate limiting to prevent abuse:
const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 1000, // Limit each IP to 1000 requests per windowMs
  message: 'Too many webhook requests'
});

app.use('/webhook', webhookLimiter);
Always use HTTPS endpoints for webhook URLs:
// ✅ Correct - HTTPS endpoint
const webhookUrl = 'https://api.yoursite.com/webhook/ai-sync';

// ❌ Incorrect - HTTP endpoint (insecure)
const webhookUrl = 'http://api.yoursite.com/webhook/ai-sync';

Error Handling

AI Sync implements exponential backoff for failed webhooks:
  • Attempt 1: Immediate
  • Attempt 2: 30 seconds delay
  • Attempt 3: 2 minutes delay
  • Attempt 4: 8 minutes delay
  • Attempt 5: 32 minutes delay
  • Final: Webhook marked as failed after 5 attempts
Return appropriate HTTP status codes:
app.post('/webhook', (req, res) => {
  try {
    // Process webhook data
    processWebhookData(req.body);
    
    // Success response
    res.status(200).json({ 
      received: true,
      timestamp: new Date().toISOString()
    });
  } catch (error) {
    // Log error for debugging
    console.error('Webhook processing error:', error);
    
    // Return error status
    res.status(500).json({ 
      error: 'Internal processing error',
      message: error.message
    });
  }
});

📊 Monitoring & Debugging

Webhook Logs

Monitor webhook delivery and performance:

Delivery Status

  • Success/failure rates
  • Response times
  • Error codes and messages
  • Retry attempts

Performance Metrics

  • Average response time
  • Peak load handling
  • Throughput statistics
  • Error rate trends

Testing Webhooks

Use tools like ngrok for local testing:
# Install ngrok
npm install -g ngrok

# Start your local server
node webhook-server.js

# Expose local server
ngrok http 3000

# Use the HTTPS URL for webhook configuration
# https://abc123.ngrok.io/webhook
Test with sample webhook payloads:
curl -X POST https://your-webhook-url.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-Webhook-Signature: sha256=test-signature" \
  -d '{
    "event": "call.ended",
    "timestamp": "2025-01-15T14:30:25.123Z",
    "data": {
      "call_id": "test_call_123",
      "call_duration": 120,
      "sentiment": "positive"
    }
  }'
I