Webhook Security Guide

// npm install express
const express = require('express');
const crypto = require('crypto');

const app = express();

// CRITICAL: Use raw body middleware — not json() — for signature verification.
// Parsing the body first (json()) can alter whitespace and break the hash.
app.use('/webhooks/ovrtxt', express.raw({ type: 'application/json' }));

const WEBHOOK_SECRET = process.env.OVRTXT_WEBHOOK_SECRET;
const TOLERANCE_SECONDS = 300; // Reject payloads older than 5 minutes

function verifyOvrtxtSignature(rawBody, headers) {
  const sigHeader = headers['x-ovrtxt-signature'] ?? '';
  const timestamp = headers['x-ovrtxt-timestamp'] ?? '';

  // 1. Reject stale payloads to prevent replay attacks
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > TOLERANCE_SECONDS) {
    throw new Error('Webhook timestamp too old — possible replay attack.');
  }

  // 2. Construct the signed string: "{timestamp}.{raw_body}"
  const signedPayload = `${timestamp}.${rawBody.toString('utf8')}`;

  // 3. Compute HMAC-SHA256 using your Webhook Secret
  const expectedSig = 'sha256=' + crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(signedPayload)
    .digest('hex');

  // 4. Timing-safe comparison — prevents timing oracle attacks
  const receivedBuf = Buffer.from(sigHeader, 'utf8');
  const expectedBuf = Buffer.from(expectedSig, 'utf8');

  if (receivedBuf.length !== expectedBuf.length) throw new Error('Signature mismatch.');

  if (!crypto.timingSafeEqual(receivedBuf, expectedBuf)) {
    throw new Error('Invalid signature — request rejected.');
  }
}

app.post('/webhooks/ovrtxt', (req, res) => {
  try {
    verifyOvrtxtSignature(req.body, req.headers);
  } catch (err) {
    console.error('Webhook auth failed:', err.message);
    return res.status(403).json({ error: err.message });
  }

  // Signature verified — safe to parse and act on the payload
  const event = JSON.parse(req.body.toString());

  switch (event.event) {
    case 'verification.completed':
      const { data } = event;
      console.log(`✓ User ${data.phone} authenticated in ${data.latencyMs}ms`);
      // → Log the user in, set your session cookie, emit WS event, etc.
      break;

    case 'verification.expired':
      console.warn(`Session ${event.data.id} expired.`);
      // → Notify the waiting browser UI to refresh
      break;
  }

  // Must respond 2xx within 10 seconds or Ovrtxt will retry
  res.status(200).json({ received: true });
});

app.listen(3000);