Webhook Security

X-Orbit-Signature: sha256=abc123def456...

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf8')
    .digest('hex');
  
  const expected = `sha256=${expectedSignature}`;
  if (!signature || signature.length !== expected.length) return false;
  
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Usage in Express — the signature is computed over the raw request body,
// so mount express.raw() for this route (express.json() would re-serialize
// the body and break verification)
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-orbit-signature'];
  const isValid = verifyWebhookSignature(
    req.body.toString('utf8'),
    signature,
    process.env.WEBHOOK_SECRET
  );
  
  if (!isValid) {
    return res.status(401).send('Invalid signature');
  }

  // Replays: refuse deliveries whose event is older than you are willing to accept
  const occurredAt = Date.parse(req.headers['x-orbit-timestamp']);
  if (Number.isNaN(occurredAt) || Date.now() - occurredAt > 10 * 60 * 1000) {
    return res.status(401).send('Stale delivery');
  }

  // Duplicates: a retry carries the same X-Orbit-Event-ID
  const eventId = req.headers['x-orbit-event-id'];
  if (alreadyProcessed(eventId)) {
    return res.status(200).send('OK');
  }
  
  // Process webhook...
  res.status(200).send('OK');
});