Webhooks

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

Navigate to Setup > Webhooks to manage your webhook configurations.

📊 Webhook Table Overview#

⚡ Quick Actions#

👁️ Viewing Webhook Details#

When you click a webhook entry in the table, you'll see a detailed view showing all of its configuration and delivery parameters.

This detail page includes:

• Title: The name of the webhook for easy identification.
• URL: The full endpoint address where HTTP POST requests are sent.
• Method: The HTTP method used (always POST).
• Form Data:
  A complete list of fields included in the payload sent to your endpoint.
  Examples: phone_number, email, first_name, last_name, address, city, country,new_user_field, powelist_id, wayan_cf, and more....

This view allows you to:

• Verify the endpoint URL and method used
• See exactly which form fields are transmitted to your external system
• Easily copy field names for integration into your endpoints

Click the yellow Back button at the top to return to the main Webhooks overview table.

Use this page whenever you need to audit, troubleshoot, or integrate with your webhooks more precisely.

🔄 Webhook Workflow#

🎛️ Webhook Configuration#

Creating a New Webhook

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#

🤖 Agent Events#

📊 Campaign Events#

💬 SMS Events#

📦 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

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();
});

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);

// ✅ 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

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:

Testing Webhooks

# 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

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