Webhook Security Best Practices

Harden callbacks with signature verification, idempotency, and key rotation.

Pre-Launch Checklist

• Allow HTTPS callback URLs only
• Validate timestamp and limit replay window
• Verify HMAC signature
• Implement idempotent event handling
• Store callback errors in audit logs

Key Rotation Policy

Rotate webhook secrets every 90 days. During rollout, accept old/new secrets briefly and remove old secret after verification.

Idempotent Processing

Track `order_no + status` as a unique event key. Return 200 for duplicates to prevent double delivery or duplicate bookkeeping.

Node.js

import crypto from 'crypto';

export function verifyWebhook({ rawBody, timestamp, signature, secret }) {
  const payload = `${timestamp}.${rawBody}`;
  const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}