flowchart LR
    A[Twilio Voice/SMS] -->|Webhook + HMAC| B[Railway Server]
    B -->|Encrypted Payload| C[Zapier Webhook]
    C -->|Validated Data| D[CRM/Database]
    B -->|Audit Log| E[Compliance Store]

// server.js - Railway deployment
const express = require('express');
const crypto = require('crypto');
const axios = require('axios');

const app = express();
app.use(express.urlencoded({ extended: false }));

// Twilio signature validation (CRITICAL for compliance)
function validateTwilioSignature(url, params, signature) {
  const authToken = process.env.TWILIO_AUTH_TOKEN;
  const data = Object.keys(params).sort().map(key => key + params[key]).join('');
  const expectedSignature = crypto
    .createHmac('sha1', authToken)
    .update(url + data)
    .digest('base64');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Webhook endpoint - receives Twilio events
app.post('/webhook/twilio', async (req, res) => {
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.headers.host}${req.originalUrl}`;
  
  // REJECT unverified requests (prevents data injection)
  if (!validateTwilioSignature(url, req.body, signature)) {
    console.error('Invalid signature - potential attack');
    return res.status(403).send('Forbidden');
  }
  
  // Encrypt sensitive data before forwarding to Zapier
  const encryptedPayload = {
    callSid: req.body.CallSid,
    from: encrypt(req.body.From), // PII encryption
    to: encrypt(req.body.To),
    status: req.body.CallStatus,
    timestamp: new Date().toISOString()
  };
  
  try {
    // Forward to Zapier webhook (use YOUR Zapier webhook URL)
    await axios.post(process.env.ZAPIER_WEBHOOK_URL, encryptedPayload, {
      headers: { 'Content-Type': 'application/json' },
      timeout: 5000
    });
    
    // Log for audit trail (compliance requirement)
    await logToComplianceStore(encryptedPayload);
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Zapier forward failed:', error.message);
    res.status(500).send('Processing error');
  }
});

function encrypt(data) {
  const cipher = crypto.createCipheriv(
    'aes-256-gcm',
    Buffer.from(process.env.ENCRYPTION_KEY, 'hex'),
    Buffer.from(process.env.IV, 'hex')
  );
  return cipher.update(data, 'utf8', 'hex') + cipher.final('hex');
}

app.listen(process.env.PORT || 3000);

# Trigger test call via Twilio API
curl -X POST "https://api.twilio.com/2010-04-01/Accounts/$TWILIO_ACCOUNT_SID/Calls.json" \
  -u "$TWILIO_ACCOUNT_SID:$TWILIO_AUTH_TOKEN" \
  -d "Url=http://demo.twilio.com/docs/voice.xml" \
  -d "To=+1234567890" \
  -d "From=$TWILIO_PHONE_NUMBER"

sequenceDiagram
    participant User
    participant TwilioAPI as Twilio Voice API
    participant TwilioNumber as Twilio Number
    participant YourServer
    participant ErrorHandler

    User->>TwilioNumber: Initiates call
    TwilioNumber->>TwilioAPI: Forward call request
    TwilioAPI->>YourServer: POST /2010-04-01/Accounts
    YourServer->>TwilioAPI: Respond with TwiML
    TwilioAPI->>User: Connect call
    Note over User,TwilioAPI: Call in progress

    User->>TwilioAPI: Ends call
    TwilioAPI->>YourServer: Call status update
    YourServer->>TwilioAPI: Acknowledge status

    User->>TwilioNumber: Invalid number
    TwilioNumber->>ErrorHandler: Trigger error handling
    ErrorHandler->>User: Notify invalid number

    User->>TwilioAPI: Network issue
    TwilioAPI->>ErrorHandler: Log network error
    ErrorHandler->>User: Notify network issue

// Test webhook handler with signature validation
const express = require('express');
const crypto = require('crypto');
const app = express();

app.use(express.urlencoded({ extended: false }));

function validateTwilioSignature(req) {
  const authToken = process.env.TWILIO_AUTH_TOKEN;
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.headers.host}${req.url}`;
  
  const data = Object.keys(req.body)
    .sort()
    .reduce((acc, key) => acc + key + req.body[key], url);
  
  const expectedSignature = crypto
    .createHmac('sha1', authToken)
    .update(Buffer.from(data, 'utf-8'))
    .digest('base64');
  
  return signature === expectedSignature;
}

app.post('/webhook/twilio', (req, res) => {
  if (!validateTwilioSignature(req)) {
    return res.status(403).send('Invalid signature');
  }
  console.log('Valid webhook:', req.body);
  res.status(200).send('<Response></Response>');
});

app.listen(3000);

curl -X POST https://your-app.railway.app/webhook/twilio \
  -H "X-Twilio-Signature: invalid_signature" \
  -d "From=+1234567890&Body=test" \
  -v

// Production barge-in handler for Twilio Voice webhooks
const express = require('express');
const crypto = require('crypto');
const app = express();

let isProcessing = false; // Race condition guard
let audioBuffer = [];

app.post('/webhook/voice', express.raw({ type: 'application/x-www-form-urlencoded' }), (req, res) => {
  // Validate Twilio signature (MANDATORY for compliance)
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.headers.host}${req.url}`;
  const authToken = process.env.TWILIO_AUTH_TOKEN;
  
  if (!validateTwilioSignature(signature, url, req.body, authToken)) {
    return res.status(403).send('Invalid signature');
  }

  const event = req.body.SpeechResult; // Twilio STT partial result
  
  if (event && !isProcessing) {
    isProcessing = true;
    audioBuffer = []; // Flush TTS buffer on interrupt
    
    // Process consent immediately
    processConsent(event).then(() => {
      isProcessing = false;
    }).catch(err => {
      console.error('Consent processing failed:', err);
      isProcessing = false;
    });
  }
  
  res.status(200).send('OK');
});

function validateTwilioSignature(signature, url, data, authToken) {
  const expectedSignature = crypto
    .createHmac('sha1', authToken)
    .update(Buffer.from(url + JSON.stringify(data), 'utf-8'))
    .digest('base64');
  return signature === expectedSignature;
}

// Railway server - Signature validation with fallback
const crypto = require('crypto');

app.post('/webhook/twilio', express.json(), (req, res) => {
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.headers.host}${req.originalUrl}`;
  
  // Compute expected signature
  const expectedSignature = crypto
    .createHmac('sha1', process.env.TWILIO_AUTH_TOKEN)
    .update(Buffer.from(url + JSON.stringify(req.body), 'utf-8'))
    .digest('base64');
  
  if (signature !== expectedSignature) {
    // Fallback: Check if request came from Zapier's IP range
    const zapierIPs = ['54.85.76.0/24', '54.172.110.0/24'];
    const clientIP = req.headers['x-forwarded-for']?.split(',')[0];
    
    if (!zapierIPs.some(range => clientIP.startsWith(range.split('/')[0]))) {
      return res.status(403).json({ error: 'Invalid signature' });
    }
  }
  
  // Process webhook
  res.status(200).send('OK');
});

// Railway server - Idempotent webhook handler with Redis lock
const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);

app.post('/webhook/twilio', async (req, res) => {
  const { CallSid, CallStatus } = req.body;
  const lockKey = `lock:${CallSid}`;
  
  // Acquire distributed lock (5s TTL)
  const acquired = await redis.set(lockKey, '1', 'EX', 5, 'NX');
  
  if (!acquired) {
    // Another instance is processing this webhook
    return res.status(200).send('Duplicate - Ignored');
  }
  
  try {
    // Process webhook atomically
    await processCallEvent(CallSid, CallStatus);
    res.status(200).send('Processed');
  } finally {
    await redis.del(lockKey);
  }
});

// Railway server - Async processing with immediate response
const axios = require('axios');

app.post('/webhook/twilio', async (req, res) => {
  const { RecordingUrl, CallSid } = req.body;
  
  // Respond immediately to Zapier
  res.status(200).send('Accepted');
  
  // Process asynchronously (no timeout constraint)
  setImmediate(async () => {
    try {
      const response = await axios.get(RecordingUrl, {
        auth: {
          username: process.env.TWILIO_ACCOUNT_SID,
          password: process.env.TWILIO_AUTH_TOKEN
        },
        timeout: 60000 // 60s for large recordings
      });
      
      // Store in database or forward to another Zap
      await storeRecording(CallSid, response.data);
    } catch (error) {
      console.error('Async processing failed:', error.message);
    }
  });
});

// server.js - Complete Twilio → Zapier → Railway integration
const express = require('express');
const crypto = require('crypto');
const axios = require('axios');
require('dotenv').config();

const app = express();
app.use(express.urlencoded({ extended: false }));
app.use(express.json());

// Environment variables (set in Railway dashboard)
const TWILIO_AUTH_TOKEN = process.env.TWILIO_AUTH_TOKEN;
const ENCRYPTION_KEY = process.env.ENCRYPTION_KEY; // 32-byte hex string
const ZAPIER_WEBHOOK_URL = process.env.ZAPIER_WEBHOOK_URL;
const PORT = process.env.PORT || 3000;

// Validate Twilio webhook signature - CRITICAL for security
function validateTwilioSignature(url, params, signature) {
  const data = Object.keys(params)
    .sort()
    .reduce((acc, key) => acc + key + params[key], url);
  
  const expectedSignature = crypto
    .createHmac('sha1', TWILIO_AUTH_TOKEN)
    .update(Buffer.from(data, 'utf-8'))
    .digest('base64');
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

// Encrypt PII fields before sending to Zapier
function encrypt(text) {
  const cipher = crypto.createCipheriv(
    'aes-256-cbc',
    Buffer.from(ENCRYPTION_KEY, 'hex'),
    Buffer.alloc(16, 0) // Use proper IV in production
  );
  let encrypted = cipher.update(text, 'utf8', 'hex');
  encrypted += cipher.final('hex');
  return encrypted;
}

// Health check for Railway deployment
app.get('/health', (req, res) => {
  res.status(200).json({ status: 'healthy', timestamp: Date.now() });
});

// Main webhook handler - receives Twilio events
app.post('/webhook/twilio', async (req, res) => {
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.headers.host}${req.originalUrl}`;
  
  // CRITICAL: Reject unsigned requests (prevents replay attacks)
  if (!validateTwilioSignature(url, req.body, signature)) {
    console.error('Invalid Twilio signature');
    return res.status(403).send('Forbidden');
  }
  
  // Extract and encrypt PII fields
  const { From, To, CallSid, RecordingUrl } = req.body;
  const encryptedPayload = {
    from: encrypt(From), // Encrypt phone numbers
    to: encrypt(To),
    callSid: CallSid, // Non-PII, safe to send plaintext
    recordingUrl: RecordingUrl ? encrypt(RecordingUrl) : null,
    timestamp: Date.now(),
    event: req.body.CallStatus || 'unknown'
  };
  
  // Forward to Zapier with retry logic
  try {
    const response = await axios.post(ZAPIER_WEBHOOK_URL, encryptedPayload, {
      headers: { 'Content-Type': 'application/json' },
      timeout: 5000 // Zapier webhooks timeout after 30s, fail fast
    });
    
    console.log('Zapier webhook success:', response.status);
    res.status(200).send('OK');
  } catch (error) {
    // Log but don't expose error details to Twilio
    console.error('Zapier webhook failed:', error.message);
    
    // Return 200 to Twilio (prevents retry storm)
    // Queue failed events for manual review
    res.status(200).send('Queued for retry');
  }
});

// Error handler for unhandled routes
app.use((req, res) => {
  res.status(404).json({ error: 'Route not found' });
});

app.listen(PORT, () => {
  console.log(`Server running on port ${PORT}`);
  console.log(`Webhook URL: https://YOUR_RAILWAY_DOMAIN/webhook/twilio`);
});

npm install express axios dotenv
node server.js
ngrok http 3000
# Use ngrok URL in Twilio webhook config

## FAQ

### Technical Questions

**How do I validate Twilio webhook signatures in a Railway-deployed application?**

Twilio signs every webhook with an HMAC-SHA1 signature in the `X-Twilio-Signature` header. Your Railway app must validate this before processing any business logic. Use your `TWILIO_AUTH_TOKEN` to compute the expected signature and compare:

```javascript
const crypto = require('crypto');

const validateTwilioSignature = (req, authToken) => {
  const signature = req.headers['x-twilio-signature'];
  const url = `https://${req.hostname}${req.originalUrl}`;
  const data = Object.keys(req.body)
    .sort()
    .reduce((acc, key) => acc + key + req.body[key], '');
  
  const expectedSignature = crypto
    .createHmac('sha1', authToken)
    .update(url + data)
    .digest('Base64');
  
  return signature === expectedSignature;
};

app.post('/webhook/twilio', (req, res) => {
  if (!validateTwilioSignature(req, process.env.TWILIO_AUTH_TOKEN)) {
    return res.status(403).send({ error: 'Invalid signature' });
  }
  // Process webhook safely
  res.status(200).send({ success: true });
});

const crypto = require('crypto');

const encrypt = (data, encryptionKey) => {
  const iv = crypto.randomBytes(16);
  const cipher = crypto.createCipheriv(
    'aes-256-gcm',
    Buffer.from(encryptionKey, 'hex'),
    iv
  );
  
  const encrypted = Buffer.concat([
    cipher.update(JSON.stringify(data), 'utf8'),
    cipher.final()
  ]);
  
  const authTag = cipher.getAuthTag();
  return {
    iv: iv.toString('hex'),
    encrypted: encrypted.toString('hex'),
    authTag: authTag.toString('hex')
  };
};

app.post('/webhook/encrypt', async (req, res) => {
  const encryptedPayload = encrypt(req.body, process.env.ENCRYPTION_KEY);
  
  const response = await axios.post(process.env.ZAPIER_WEBHOOK_URL, {
    payload: encryptedPayload,
    timestamp: Date.now()
  }, {
    headers: { 'Content-Type': 'application/json' },
    timeout: 10000
  });
  
  res.status(200).send({ status: 'encrypted' });
});

const Redis = require('ioredis');
const redis = new Redis(process.env.REDIS_URL);

app.post('/webhook/process', async (req, res) => {
  const lockKey = `lock:${req.body.customerId}`;
  const acquired = await redis.set(lockKey, '1', 'EX', 30, 'NX');
  
  if (!acquired) {
    return res.status(429).send({ error: 'Processing' });
  }
  
  try {
    // Process webhook
    await processWebhook(req.body);
    res.status(200).send({ success: true });
  } finally {
    await redis.del(lockKey);
  }
});