Batch Webhooks

What are Webhooks?

Webhooks are HTTP callbacks that Dialgen sends to your server when specific events occur. Instead of polling for updates, your application receives instant notifications.

Available Webhooks

onBatchComplete

Triggered when all calls in the batch are finished.

{
  "event": "batch.completed",
  "batchId": "batch_123",
  "agentId": "agent_456",
  "userId": "user_789",
  "statistics": {
    "total": 1000,
    "processed": 1000,
    "succeeded": 850,
    "failed": 150,
    "percentComplete": 100,
    "successRate": 85
  },
  "timestamps": {
    "createdAt": "2025-11-15T14:00:00.000Z",
    "startedAt": "2025-11-15T14:05:00.000Z",
    "completedAt": "2025-11-15T16:30:00.000Z"
  }
}

onCallComplete

Triggered after each individual call completes. Includes full call data:

{
  "success": true,
  "callData": {
    "id": "call_123",
    "contactId": "contact_456",
    "agentId": "agent_789",
    "batchId": "batch_abc",
    "status": "COMPLETED",
    "startTime": "2025-11-15T14:30:00.000Z",
    "endTime": "2025-11-15T14:33:00.000Z",
    "duration": 180,
    "phoneNumber": "+1234567890",
    "contactName": "John Doe",
    "transcription": [...],
    "recordingUrl": "https://...",
    "summary": "Call summary text...",
    "metricJson": {
      "intent": "SALES_INQUIRY",
      "sentiment": "positive",
      "confidence": 0.95
    }
  },
  "metricSchema": {...}
}

onBatchFailed

Triggered if the batch fails to process:

{
  "event": "batch.failed",
  "batchId": "batch_123",
  "agentId": "agent_456",
  "error": "Insufficient call minutes",
  "code": "INSUFFICIENT_CREDITS",
  "timestamp": "2025-11-15T14:05:00.000Z"
}

Configuring Webhooks

Add webhook URLs when creating your batch:

{
  "agentId": "agent_123",
  "userId": "user_456",
  "contacts": [...],
  "options": {
    "webhooks": {
      "onBatchComplete": "https://api.yourcompany.com/webhooks/batch-complete",
      "onCallComplete": "https://api.yourcompany.com/webhooks/call-complete",
      "onBatchFailed": "https://api.yourcompany.com/webhooks/batch-failed"
    }
  }
}

Implementing Webhook Endpoints

Node.js Example

const express = require('express');
const app = express();

app.use(express.json());

// Handle call completion
app.post('/webhooks/call-complete', (req, res) => {
  const { callData } = req.body;
  
  console.log(`Call ${callData.id} completed`);
  console.log(`Duration: ${callData.duration}s`);
  console.log(`Summary: ${callData.summary}`);
  
  // Process call data
  // - Update CRM
  // - Send notifications
  // - Trigger workflows
  
  res.status(200).json({ received: true });
});

// Handle batch completion
app.post('/webhooks/batch-complete', (req, res) => {
  const { batchId, statistics } = req.body;
  
  console.log(`Batch ${batchId} completed`);
  console.log(`Success rate: ${statistics.successRate}%`);
  
  // Process batch completion
  // - Generate reports
  // - Send summary email
  // - Archive batch data
  
  res.status(200).json({ received: true });
});

app.listen(3000);

Python Example

from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhooks/call-complete', methods=['POST'])
def call_complete():
    data = request.json
    call_data = data['callData']
    
    print(f"Call {call_data['id']} completed")
    print(f"Duration: {call_data['duration']}s")
    print(f"Summary: {call_data['summary']}")
    
    # Process call data
    # - Update CRM
    # - Send notifications
    # - Trigger workflows
    
    return jsonify({'received': True}), 200

@app.route('/webhooks/batch-complete', methods=['POST'])
def batch_complete():
    data = request.json
    batch_id = data['batchId']
    statistics = data['statistics']
    
    print(f"Batch {batch_id} completed")
    print(f"Success rate: {statistics['successRate']}%")
    
    # Process batch completion
    # - Generate reports
    # - Send summary email
    # - Archive batch data
    
    return jsonify({'received': True}), 200

if __name__ == '__main__':
    app.run(port=3000)

Best Practices

Respond Quickly

Respond within 5 seconds to avoid retries
Return a 2xx status code immediately
Process data asynchronously if needed

app.post('/webhooks/call-complete', async (req, res) => {
  // Respond immediately
  res.status(200).json({ received: true });
  
  // Process asynchronously
  processCallData(req.body).catch(console.error);
});

Handle Idempotency

Webhooks may be delivered multiple times. Use idempotency keys:

const processedWebhooks = new Set();

app.post('/webhooks/call-complete', (req, res) => {
  const callId = req.body.callData.id;
  
  if (processedWebhooks.has(callId)) {
    return res.status(200).json({ received: true, duplicate: true });
  }
  
  processedWebhooks.add(callId);
  
  // Process webhook
  processCallData(req.body);
  
  res.status(200).json({ received: true });
});

Secure Your Endpoints

Verify webhook authenticity:

const crypto = require('crypto');

function verifyWebhook(req, secret) {
  const signature = req.headers['x-dialgen-signature'];
  const payload = JSON.stringify(req.body);
  
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');
  
  return signature === expectedSignature;
}

app.post('/webhooks/call-complete', (req, res) => {
  if (!verifyWebhook(req, process.env.WEBHOOK_SECRET)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }
  
  // Process webhook
  res.status(200).json({ received: true });
});

Log Everything

Keep detailed logs for debugging:

app.post('/webhooks/call-complete', (req, res) => {
  console.log('Webhook received:', {
    timestamp: new Date().toISOString(),
    callId: req.body.callData?.id,
    status: req.body.callData?.status,
    headers: req.headers
  });
  
  // Process webhook
  
  res.status(200).json({ received: true });
});

Handle Errors Gracefully

app.post('/webhooks/call-complete', async (req, res) => {
  try {
    await processCallData(req.body);
    res.status(200).json({ received: true });
  } catch (error) {
    console.error('Webhook processing error:', error);
    // Still return 200 to prevent retries for application errors
    res.status(200).json({ received: true, error: error.message });
  }
});

Retry Logic

If your endpoint fails, Dialgen will retry:

Retry Attempts: Up to 3 times
Retry Delay: Exponential backoff (1s, 5s, 25s)
Timeout: 30 seconds per attempt

If all retries fail, the webhook is dropped. Implement proper error handling and logging.

Testing Webhooks

Use ngrok for Local Testing

# Start ngrok
ngrok http 3000

# Use the ngrok URL in your webhook configuration
https://abc123.ngrok.io/webhooks/call-complete

Test with curl

curl -X POST https://your-server.com/webhooks/call-complete \
  -H "Content-Type: application/json" \
  -d '{
    "success": true,
    "callData": {
      "id": "call_test_123",
      "status": "COMPLETED",
      "duration": 180
    }
  }'

Common Use Cases

Update CRM

app.post('/webhooks/call-complete', async (req, res) => {
  const { callData } = req.body;
  
  await crm.updateContact({
    id: callData.contactId,
    lastCallDate: callData.startTime,
    callSummary: callData.summary,
    sentiment: callData.metricJson.sentiment
  });
  
  res.status(200).json({ received: true });
});

Send Notifications

app.post('/webhooks/batch-complete', async (req, res) => {
  const { batchId, statistics } = req.body;
  
  await sendEmail({
    to: 'team@company.com',
    subject: `Batch ${batchId} Completed`,
    body: `
      Total Calls: ${statistics.total}
      Success Rate: ${statistics.successRate}%
      Succeeded: ${statistics.succeeded}
      Failed: ${statistics.failed}
    `
  });
  
  res.status(200).json({ received: true });
});

Trigger Workflows

app.post('/webhooks/call-complete', async (req, res) => {
  const { callData } = req.body;
  
  if (callData.metricJson.intent === 'INTERESTED') {
    await workflow.trigger('send-follow-up-email', {
      contactId: callData.contactId,
      summary: callData.summary
    });
  }
  
  res.status(200).json({ received: true });
});

Getting Started

Core Concepts

Batch Calling

Multilingual Support

Call Management

Custom Functions

Analytics & Processing

Integrations

What are Webhooks?

Available Webhooks

onBatchComplete

onCallComplete

onBatchFailed

Configuring Webhooks

Implementing Webhook Endpoints

Node.js Example

Python Example

Best Practices

Respond Quickly

Handle Idempotency

Secure Your Endpoints

Log Everything

Handle Errors Gracefully

Retry Logic

Testing Webhooks

Use ngrok for Local Testing

Test with curl

Common Use Cases

Update CRM

Send Notifications

Trigger Workflows

Next Steps

Monitoring

Call Metrics API

​What are Webhooks?

​Available Webhooks

​onBatchComplete

​onCallComplete

​onBatchFailed

​Configuring Webhooks

​Implementing Webhook Endpoints

​Node.js Example

​Python Example

​Best Practices

​Respond Quickly

​Handle Idempotency

​Secure Your Endpoints

​Log Everything

​Handle Errors Gracefully

​Retry Logic

​Testing Webhooks

​Use ngrok for Local Testing

​Test with curl

​Common Use Cases

​Update CRM

​Send Notifications

​Trigger Workflows

​Next Steps

Monitoring

Call Metrics API

What are Webhooks?

Available Webhooks

onBatchComplete

onCallComplete

onBatchFailed

Configuring Webhooks

Implementing Webhook Endpoints

Node.js Example

Python Example

Best Practices

Respond Quickly

Handle Idempotency

Secure Your Endpoints

Log Everything

Handle Errors Gracefully

Retry Logic

Testing Webhooks

Use ngrok for Local Testing

Test with curl

Common Use Cases

Update CRM

Send Notifications

Trigger Workflows

Next Steps