Webhook Integration Guide

{
  "event_type": "call.completed",
  "timestamp": "2025-04-30T15:23:47Z",
  "version": "1.0",
  "environment": "production",
  "webhook_id": "whk_12345abcdef",
  "data": {
    "call_id": "call_9876543210",
    "phone_number": "+15551234567",
    "caller_number": "+15559876543",
    "caller_name": "John Smith",
    "call_start": "2025-04-30T15:21:32Z",
    "call_end": "2025-04-30T15:23:47Z",
    "duration_seconds": 135,
    "direction": "inbound",
    "status": "completed",
    "ai_handled": true,
    "forwarded": false,
    "summary": "John called about his recent order #12345 which hasn't arrived yet. The AI confirmed the order is in transit and provided the tracking number.",
    "topics": ["order status", "shipping", "tracking"],
    "sentiment": "neutral",
    "urgency": "medium",
    "transcription_url": "https://api.phoneshield.ai/v1/calls/call_9876543210/transcript",
    "recording_url": "https://api.phoneshield.ai/v1/calls/call_9876543210/recording",
    "metadata": {
      "customer_id": "cust_987654",
      "account_type": "premium",
      "source": "website"
    }
  }
}

// Node.js webhook receiver example with Express
const express = require('express');
const crypto = require('crypto');
const app = express();

// For parsing JSON requests
app.use(express.json());

// Your webhook secret from PhoneShield dashboard
const WEBHOOK_SECRET = 'your_webhook_secret';

// Verify webhook signature
function verifySignature(payload, signature) {
  const hmac = crypto.createHmac('sha256', WEBHOOK_SECRET);
  const calculatedSignature = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(calculatedSignature, 'hex'),
    Buffer.from(signature, 'hex')
  );
}

app.post('/phoneshield-webhook', (req, res) => {
  const signature = req.headers['x-phoneshield-signature'];
  
  // Verify the webhook signature
  try {
    const isValid = verifySignature(
      JSON.stringify(req.body),
      signature
    );
    
    if (!isValid) {
      console.error('Invalid webhook signature');
      return res.status(401).send('Invalid signature');
    }
    
    // Process the webhook event
    const event = req.body;
    console.log('Received event:', event.event_type);
    
    switch(event.event_type) {
      case 'call.completed':
        handleCompletedCall(event.data);
        break;
      case 'transcription.completed':
        handleTranscription(event.data);
        break;
      // Handle other event types...
      default:
        console.log('Unhandled event type:', event.event_type);
    }
    
    // Always return a 200 response quickly
    res.status(200).send('Webhook received');
    
  } catch (error) {
    console.error('Error processing webhook:', error);
    res.status(500).send('Error processing webhook');
  }
});

function handleCompletedCall(callData) {
  // Implement your business logic here
  console.log('Processing completed call:', callData.call_id);
  // e.g., update CRM, send notification, etc.
}

function handleTranscription(transcriptionData) {
  // Process transcription data
  console.log('New transcription available:', transcriptionData.call_id);
  // e.g., analyze content, store in database, etc.
}

const PORT = process.env.PORT || 3000;
app.listen(PORT, () => {
  console.log(`Webhook server running on port ${PORT}`);
});