Skip to main content
Webhooks enable real-time communication between AI Sync and external systems by sending HTTP POST requests when specific events occur in your system. Webhook Overview Navigate to Setup > Webhooks to manage your webhook configurations.

📊 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

View Endpoints

Monitor webhook performance and delivery status

🔄 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 Configuration

Creating a New Webhook Add Webhook Interface How to Add a Webhook:
  1. Go to Setup > Webhooks
    Click the yellow Add button to open the Add Webhook form.
  2. Fill out Webhook Details:
    • Title:
      Enter a clear, descriptive name for your webhook.
      Example: Home
    • Powelist:
      Select the appropriate option from the Powelist dropdown. This field lets you choose a predefined set or type related to your webhook logic.
    • Endpoint:
      Use the dropdown menu to select the desired endpoint or event trigger for your webhook.
      Example: Contact , Contact Delete

      Tip: You can select a single or multiple event types as needed for your integration.
    After filling in all fields, click the purple Submit button to complete adding the webhook.
Tip: Hover over the event field to see additional info for each webhook trigger.

🎪 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"
    }
  }'