Documentation

Complete guide to webhooks, debugging, and real-time event monitoring with HookMetry

Signature Validation

Signature validation ensures that webhooks are authentic and haven't been tampered with. It prevents unauthorized parties from sending fake webhooks to your endpoint.

How Signature Validation Works

1

Shared Secret

Both you and the webhook provider share a secret key (never transmitted with webhooks)

2

HMAC Generation

Provider creates an HMAC hash of the payload using the secret key (typically SHA-256)

3

Signature Sent

The signature is included in a header (e.g., X-Webhook-Signature)

4

You Verify

Compute the same HMAC with your secret and compare - if they match, the webhook is authentic

Example: Verifying HMAC SHA-256 (Node.js)

const crypto = require('crypto');

function verifyWebhookSignature(payload, signature, secret) {
  // Compute HMAC hash of the payload
  const computedSignature = crypto
    .createHmac('sha256', secret)
    .update(JSON.stringify(payload))
    .digest('hex');
  
  // Compare signatures (timing-safe comparison)
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(computedSignature)
  );
}

// Usage
const isValid = verifyWebhookSignature(
  req.body,
  req.headers['x-webhook-signature'],
  process.env.WEBHOOK_SECRET
);

if (!isValid) {
  return res.status(401).json({ error: 'Invalid signature' });
}

Security Benefits

  • • Prevents replay attacks
  • • Ensures data integrity
  • • Authenticates sender
  • • Detects tampering

Without Validation

  • • Anyone can send fake events
  • • Data can be modified
  • • Security vulnerabilities
  • • Potential financial loss

HookMetry Advantage:

HookMetry automatically validates signatures for Stripe, GitHub, and custom HMAC webhooks. You can see validation results in real-time, making debugging authentication issues effortless.