Webhook Integration Guide

✅ https://api.yourcompany.com/webhook/hamsa
✅ https://webhook.example.com/hamsa/events
✅ https://your-app.herokuapp.com/webhooks/calls

❌ http://api.yourcompany.com/webhook (HTTP not allowed)
❌ https://192.168.1.100/webhook (local IPs not accessible)
❌ https://localhost:3000/webhook (localhost not accessible)

# Install ngrok
npm install -g ngrok
# or brew install ngrok

# Start your local server
node server.js  # Runs on port 3000

# In another terminal, start ngrok
ngrok http 3000

# Use the ngrok HTTPS URL in your webhook configuration
# Example: https://abc123.ngrok.io/webhook

# Generate a random token (Linux/Mac)
openssl rand -base64 32

# Or use Node.js
node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"

# Or use Python
python -c "import secrets; print(secrets.token_urlsafe(32))"

{
  agentId: string,           // Required: Your Hamsa agent ID
  params?: object,           // Optional: Custom parameters (ANY data you want)
  userId?: string,           // Optional: User identifier for tracking
  voiceEnablement?: boolean, // Optional: Enable voice (default: true)
  preferHeadphonesForIosDevices?: boolean, // Optional: iOS optimization
  connectionDelay?: {        // Optional: Platform-specific delays
    android?: number,
    ios?: number,
    default?: number
  }
}

params: {
  // IDENTIFIERS (highly recommended - used to match webhook to your records)
  user_id: string,              // Your user/customer ID
  session_id: string,           // Unique session identifier
  application_id: string,       // Application/form ID

  // CONTEXT DATA (optional - helps agent personalize conversation)
  user_name: string,            // User's name
  user_email: string,           // User's email
  user_phone: string,           // User's phone

  // BUSINESS DATA (optional - agent can reference during conversation)
  job_title: string,            // Job position
  company_name: string,         // Company name
  custom_field_1: string,       // Any other data
  custom_field_2: number,       // Can be strings, numbers, booleans
  custom_field_3: boolean,

  // INSTRUCTIONS (optional - guide agent behavior)
  interview_questions: string,  // JSON stringified array of questions
  context_data: string,         // Any additional context (CV, resume, etc.)
}

{
  "agentId": "agent-123-abc",
  "params": {
    "application_id": "12345",
    "user_id": "user-789",
    "session_id": "sess-abc-def",
    "candidate_name": "John Doe",
    "candidate_email": "[email protected]",
    "candidate_phone": "+1234567890",
    "job_title": "Software Engineer",
    "company_name": "Acme Corp",
    "interview_questions": "[\"Tell me about your experience\",\"What are your salary expectations?\"]",
    "custom_note": "VIP candidate",
    "priority_level": 1,
    "require_background_check": true
  },
  "userId": "user-789",
  "voiceEnablement": true
}

{
  "eventType": "call.ended",
  "callId": "call_uuid_12345",
  "timestamp": "2024-01-15T14:30:00.000Z",
  "projectId": "proj_abc123",
  "agentId": "agent_xyz789",
  "agentName": "Customer Support Agent",
  "data": {
    // Event-specific data
  }
}

{
  "eventType": "call.ended",
  "callId": "call_uuid_12345",
  "timestamp": "2024-01-15T14:35:00.000Z",
  "projectId": "proj_abc123",
  "agentId": "agent_xyz789",
  "agentName": "Customer Support Agent",
  "data": {
    "timestamp": "2025-11-27T09:10:35.000Z",
    "data": {
      "conversationId": "conv-123-abc-456-def",
      "conversationRecording": "https://hamsa-recordings.s3.amazonaws.com/conv-123.mp3",
      "transcription": [
        { "Agent": "Hello! Thank you for joining. What is your name?" },
        { "User": "Hi, my name is John Doe." },
        { "Agent": "Nice to meet you, John. Can you tell me about your experience?" },
        { "User": "I have 5 years of experience in software development." },
        { "Agent": "Excellent. What are your salary expectations?" },
        { "User": "I'm looking for around 80,000 dollars per year." },
        { "Agent": "Thank you. What is your notice period?" },
        { "User": "I have a 2-week notice period." },
        { "Agent": "Great! That concludes our interview. Thank you!" },
        { "User": "Thank you!" }
      ],
      "outcomeResult": {
        "application_id": "12345",
        "user_id": "user-789",
        "session_id": "sess-abc-def",
        "candidate_name": "John Doe",
        "candidate_email": "[email protected]",
        "candidate_phone": "+1234567890",
        "job_title": "Software Engineer",
        "company_name": "Acme Corp",
        "interview_questions": "[\"Tell me about your experience\",\"What are your salary expectations?\"]",
        "custom_note": "VIP candidate",
        "priority_level": 1,
        "require_background_check": true,
        "expectedSalary": "80000 dollars per year",
        "noticePeriod": "2 weeks",
        "number_of_speakers": "1",
        "sentiment_score": 0.8
      }
    }
  }
}

{
  Agent?: string,  // Present when agent spoke
  User?: string    // Present when user spoke
}

{
  "application_id": "12345",
  "user_id": "user-789",
  "session_id": "sess-abc-def",
  "candidate_name": "John Doe",
  "candidate_email": "[email protected]",
  "candidate_phone": "+1234567890",
  "job_title": "Software Engineer",
  "company_name": "Acme Corp",
  "interview_questions": "[...]",
  "custom_note": "VIP candidate",
  "priority_level": 1,
  "require_background_check": true
}

{
  "expectedSalary": "80000 dollars per year",
  "noticePeriod": "2 weeks",
  "number_of_speakers": "1",
  "sentiment_score": 0.8
}

async function handleCallStarted(event) {
  const { callId, data } = event;
  const { callDirection, fromNumber, toNumber, params } = data.data;

  console.log(`Call started: ${callId}`);
  console.log(`Direction: ${callDirection}`);
  console.log(`From: ${fromNumber} To: ${toNumber}`);

  // Store initial call data
  await database.calls.create({
    callId,
    direction: callDirection,
    fromNumber,
    toNumber,
    customParams: params,
    status: 'in_progress',
    startedAt: data.callStartedAt
  });
}

async function handleTranscription(event) {
  const { callId, data } = event;
  const { speaker, text, confidence } = data.data;

  // Store real-time transcription
  await database.transcriptions.create({
    callId,
    speaker,
    text,
    confidence,
    timestamp: event.timestamp
  });

  // Optionally trigger real-time actions
  if (speaker === 'user' && text.toLowerCase().includes('urgent')) {
    await notifySupport({
      callId,
      message: 'User mentioned urgent issue',
      transcript: text
    });
  }
}

async function handleToolExecution(event) {
  const { callId, data } = event;
  const { toolName, input, output, duration } = data.data;

  console.log(`Tool executed: ${toolName}`);
  console.log(`Duration: ${duration}ms`);

  // Log tool usage
  await database.toolExecutions.create({
    callId,
    toolName,
    input,
    output,
    duration,
    executedAt: event.timestamp
  });
}

app.post('/webhook', async (req, res) => {
  try {
    // 1. Verify authentication
    if (!verifyToken(req)) {
      console.warn('Authentication failed:', {
        ip: req.ip,
        headers: req.headers
      });
      return res.status(401).json({ error: 'Unauthorized' });
    }

    // 2. Validate payload structure
    const event = req.body;
    if (!event.callId || !event.eventType) {
      console.error('Invalid payload:', event);
      return res.status(400).json({ error: 'Invalid payload' });
    }

    // 3. Validate event type
    const validEventTypes = [
      'call.started',
      'call.answered',
      'transcription.update',
      'tool.executed',
      'call.ended'
    ];

    if (!validEventTypes.includes(event.eventType)) {
      console.warn('Unknown event type:', event.eventType);
      // Still return 200 to acknowledge receipt
      return res.status(200).json({
        received: true,
        warning: 'Unknown event type'
      });
    }

    // 4. Process event (with timeout)
    const timeoutPromise = new Promise((_, reject) => {
      setTimeout(() => reject(new Error('Processing timeout')), 4000);
    });

    const processingPromise = processEvent(event);

    await Promise.race([processingPromise, timeoutPromise]);

    // 5. Respond successfully
    res.status(200).json({ received: true });

  } catch (error) {
    console.error('Webhook error:', {
      error: error.message,
      stack: error.stack,
      body: req.body
    });

    // Still return 200 to prevent retries for processing errors
    // Log the error for investigation
    res.status(200).json({
      received: true,
      processing_error: true,
      error_id: generateErrorId()
    });
  }
});

function generateErrorId() {
  return `err_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}

const Joi = require('joi');

const eventSchema = Joi.object({
  eventType: Joi.string().required(),
  callId: Joi.string().uuid().required(),
  timestamp: Joi.string().isoDate().required(),
  projectId: Joi.string().required(),
  agentId: Joi.string().required(),
  agentName: Joi.string().required(),
  data: Joi.object().required(),
});

function validateEvent(event) {
  const { error, value } = eventSchema.validate(event);

  if (error) {
    console.error('Validation error:', error.details);
    return { valid: false, error: error.details };
  }

  return { valid: true, value };
}

// Usage
app.post('/webhook', async (req, res) => {
  const validation = validateEvent(req.body);

  if (!validation.valid) {
    return res.status(400).json({
      error: 'Invalid payload',
      details: validation.error
    });
  }

  // Process validated event
  await processEvent(validation.value);
  res.status(200).json({ received: true });
});

const redis = require('redis');
const client = redis.createClient();

async function isEventProcessed(event) {
  const eventKey = `webhook:${event.callId}:${event.eventType}:${event.timestamp}`;

  // Check if already processed
  const exists = await client.exists(eventKey);
  if (exists) {
    return true;
  }

  // Mark as processed (expire after 24 hours)
  await client.setex(eventKey, 86400, 'processed');
  return false;
}

app.post('/webhook', async (req, res) => {
  const event = req.body;

  // Check for duplicates
  const alreadyProcessed = await isEventProcessed(event);
  if (alreadyProcessed) {
    console.log('Duplicate event, skipping:', event.callId);
    return res.status(200).json({
      received: true,
      duplicate: true
    });
  }

  // Process event
  await processEvent(event);

  res.status(200).json({ received: true });
});

async function processEventIdempotent(event) {
  const eventId = `${event.callId}-${event.eventType}-${event.timestamp}`;

  try {
    // Attempt to create event record (unique constraint on eventId)
    await database.webhookEvents.create({
      eventId,
      callId: event.callId,
      eventType: event.eventType,
      eventData: event,
      processedAt: new Date(),
      status: 'processing'
    });

    // Process event
    await processEvent(event);

    // Update status
    await database.webhookEvents.update({
      where: { eventId },
      data: { status: 'completed' }
    });

  } catch (error) {
    if (error.code === 'P2002') { // Unique constraint violation
      console.log('Duplicate event detected:', eventId);
      return { duplicate: true };
    }
    throw error;
  }

  return { duplicate: false };
}

// ✅ GOOD - Store tokens securely
require('dotenv').config();
const WEBHOOK_SECRET = process.env.WEBHOOK_SECRET;

// ❌ BAD - Never hardcode tokens
const WEBHOOK_SECRET = 'Bearer abc123';  // Don't do this!

// ✅ GOOD - Validate token format
function isValidBearerToken(token) {
  return token && token.startsWith('Bearer ') && token.length > 20;
}

// ✅ GOOD - Rotate tokens periodically
async function rotateWebhookToken() {
  const newToken = `Bearer ${crypto.randomBytes(32).toString('base64')}`;

  // Update in secure storage
  await secretManager.updateSecret('WEBHOOK_SECRET', newToken);

  // Update in Hamsa dashboard
  await hamsaApi.updateAgentWebhook({
    agentId: 'agent-123',
    webhookAuth: {
      authKey: 'bearer',
      authSecret: newToken
    }
  });

  console.log('Webhook token rotated successfully');
}

const rateLimit = require('express-rate-limit');

const webhookLimiter = rateLimit({
  windowMs: 1 * 60 * 1000, // 1 minute
  max: 100, // Limit each IP to 100 requests per windowMs
  message: 'Too many webhook requests from this IP',
  standardHeaders: true,
  legacyHeaders: false,
  skip: (req) => {
    // Skip rate limiting for valid tokens
    return verifyToken(req);
  }
});

app.post('/webhook', webhookLimiter, verifyToken, async (req, res) => {
  // Process webhook
});

const ALLOWED_IPS = [
  '34.123.45.67',  // Hamsa webhook server IP
  '52.89.12.34'    // Backup server IP
];

function checkIpWhitelist(req, res, next) {
  const clientIp = req.ip || req.connection.remoteAddress;

  if (!ALLOWED_IPS.includes(clientIp)) {
    console.warn('Unauthorized IP:', clientIp);
    return res.status(403).json({ error: 'Forbidden' });
  }

  next();
}

app.post('/webhook', checkIpWhitelist, verifyToken, async (req, res) => {
  // Process webhook
});

async function syncToCRM(event) {
  if (event.eventType !== 'call.ended') return;

  const { outcomeResult, transcription } = event.data.data;
  const { fromNumber } = event.data.data;

  // Build transcript text
  const transcriptText = transcription
    .map(turn => Object.values(turn)[0])
    .join('\n');

  // Update customer record
  await crm.contacts.upsert({
    where: { phone: fromNumber },
    update: {
      lastCallDate: event.timestamp,
      lastCallDuration: event.data.data.callDuration,
      lastCallNotes: transcriptText,
      customFields: {
        intent: outcomeResult.intent,
        sentiment: outcomeResult.sentiment_score,
        resolved: outcomeResult.resolved
      }
    },
    create: {
      phone: fromNumber,
      firstCallDate: event.timestamp,
      source: 'ai_agent'
    }
  });

  // Create activity record
  await crm.activities.create({
    type: 'phone_call',
    contactPhone: fromNumber,
    subject: `AI Agent Call - ${outcomeResult.intent || 'General'}`,
    description: transcriptText,
    outcome: outcomeResult.resolved ? 'resolved' : 'needs_followup',
    recordingUrl: event.data.data.conversationRecording,
    date: event.timestamp
  });
}

async function updateAnalytics(event) {
  if (event.eventType !== 'call.ended') return;

  const { callDuration, outcomeResult } = event.data.data;

  await analytics.track({
    event: 'Call Completed',
    properties: {
      callId: event.callId,
      agentId: event.agentId,
      agentName: event.agentName,
      duration: callDuration,
      intent: outcomeResult.intent,
      sentiment: outcomeResult.sentiment_score,
      resolved: outcomeResult.resolved,
      speakers: outcomeResult.number_of_speakers,
      timestamp: event.timestamp
    }
  });

  // Update real-time dashboard metrics
  await dashboard.increment('total_calls');
  await dashboard.increment(`calls_by_intent.${outcomeResult.intent}`);
  await dashboard.addToAverage('average_duration', callDuration);

  if (outcomeResult.resolved) {
    await dashboard.increment('resolved_calls');
  }
}

async function sendNotifications(event) {
  if (event.eventType !== 'call.ended') return;

  const { outcomeResult, callDuration } = event.data.data;

  // High-priority notifications
  if (outcomeResult.priority === 'urgent' || !outcomeResult.resolved) {
    await slack.sendMessage({
      channel: '#support-team',
      text: '🚨 Urgent call requires attention',
      blocks: [
        {
          type: 'section',
          text: {
            type: 'mrkdwn',
            text: `*Call ID:* ${event.callId}\n*Agent:* ${event.agentName}\n*Duration:* ${callDuration}s`
          }
        },
        {
          type: 'section',
          fields: [
            { type: 'mrkdwn', text: `*Intent:*\n${outcomeResult.intent || 'Unknown'}` },
            { type: 'mrkdwn', text: `*Resolved:*\n${outcomeResult.resolved ? '✅ Yes' : '❌ No'}` },
            { type: 'mrkdwn', text: `*Sentiment:*\n${outcomeResult.sentiment_score || 'N/A'}` }
          ]
        },
        {
          type: 'actions',
          elements: [
            {
              type: 'button',
              text: { type: 'plain_text', text: 'View Details' },
              url: `https://dashboard.example.com/calls/${event.callId}`
            }
          ]
        }
      ]
    });
  }

  // Email summary
  await emailService.send({
    to: '[email protected]',
    subject: `Call Summary - ${event.callId}`,
    template: 'call-summary',
    data: {
      callId: event.callId,
      agentName: event.agentName,
      duration: callDuration,
      transcript: event.data.data.transcription,
      outcome: outcomeResult,
      recordingUrl: event.data.data.conversationRecording
    }
  });
}

# Test basic connectivity
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"test": true}'

# Test with authentication
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_token" \
  -d '{"test": true}'

# Test with full call.ended payload
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer your_secret_token" \
  -d '{
    "eventType": "call.ended",
    "callId": "test-call-123",
    "timestamp": "2024-01-15T14:35:00.000Z",
    "projectId": "proj_test",
    "agentId": "agent_test",
    "agentName": "Test Agent",
    "data": {
      "timestamp": "2024-01-15T14:35:00.000Z",
      "data": {
        "conversationId": "conv-test-123",
        "conversationRecording": "https://example.com/recording.mp3",
        "transcription": [
          {"Agent": "Hello, how can I help you?"},
          {"User": "I need assistance."}
        ],
        "outcomeResult": {
          "application_id": "12345",
          "user_id": "user-789",
          "expectedSalary": "80000",
          "noticePeriod": "2 weeks"
        }
      }
    }
  }'

// Add comprehensive logging
const winston = require('winston');

const logger = winston.createLogger({
  level: 'info',
  format: winston.format.json(),
  transports: [
    new winston.transports.File({ filename: 'webhook-errors.log', level: 'error' }),
    new winston.transports.File({ filename: 'webhook-all.log' })
  ]
});

app.post('/webhook', async (req, res) => {
  const event = req.body;

  logger.info('Webhook received', {
    eventType: event.eventType,
    callId: event.callId,
    timestamp: event.timestamp,
    ip: req.ip
  });

  try {
    await processEvent(event);

    logger.info('Webhook processed successfully', {
      callId: event.callId,
      eventType: event.eventType
    });

    res.status(200).json({ received: true });

  } catch (error) {
    logger.error('Webhook processing failed', {
      callId: event.callId,
      eventType: event.eventType,
      error: error.message,
      stack: error.stack
    });

    // Still return 200
    res.status(200).json({
      received: true,
      processing_error: true
    });
  }
});

YOU SEND (Initiation):
params: { application_id: "12345", user_name: "John", ... }

         ↓ [ Call Happens ] ↓

YOU RECEIVE (Webhook):
outcomeResult: {
  application_id: "12345",     // ← Your data (echoed)
  user_name: "John",           // ← Your data (echoed)
  expectedSalary: "80k",       // ← New data (collected)
  noticePeriod: "2 weeks"      // ← New data (collected)
}