Authentication

Webhook Security

Every delivery is signed with HMAC-SHA256 using your webhook secret. The signed material is the X-Webhook-Timestamp header value, a period, then the raw request body — so a captured delivery cannot be replayed later with the signature still verifying. Verify the signature, then reject deliveries whose timestamp is more than five minutes old.

Verifying Signatures (Node.js)

import crypto from 'crypto';

export function verifyWebhookSignature(
  payload: string,
  timestamp: string,
  signature: string,
  secret: string
): boolean {
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(`${timestamp}.${payload}`)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(hmac),
    Buffer.from(signature)
  );
}

// In your webhook handler:
const signature = req.headers['x-webhook-signature'];
const timestamp = req.headers['x-webhook-timestamp'];
const payload = req.body.toString();

if (!verifyWebhookSignature(payload, timestamp, signature, webhookSecret)) {
  return res.status(401).json({ error: 'Invalid signature' });
}

// Replay window: reject deliveries older than 5 minutes.
if (Math.abs(Date.now() - Date.parse(timestamp)) > 5 * 60 * 1000) {
  return res.status(401).json({ error: 'Stale delivery' });
}

// Process webhook...

Every delivery carries four headers: X-Webhook-Signature, X-Webhook-Timestamp, X-Webhook-Event and X-Webhook-Id. Always verify the signature before processing an event.