Documentation

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

Webhook Security

Webhooks are a powerful integration method but come with security considerations. Follow these practices to keep your application safe.

Critical Security Measures

1. Always Verify Signatures

Without signature verification, anyone can send fake webhooks to your endpoint. This could lead to unauthorized actions, data corruption, or financial loss.

// DANGEROUS - No verification
app.post('/webhook', (req, res) => {
  processPayment(req.body); // Anyone can trigger this!
});

// ✅ SAFE - Signature verified
app.post('/webhook', (req, res) => {
  if (!verifySignature(req)) {
    return res.status(401).send('Invalid signature');
  }
  processPayment(req.body);
});

2. Use HTTPS Only

Never use HTTP for webhook endpoints. Unencrypted traffic exposes sensitive data and allows man-in-the-middle attacks.

https://hookmetry.com/webhook/ep_abc123
http://hookmetry.com/webhook/ep_abc123

3. Validate Payload Schema

Don't assume incoming data is well-formed. Validate structure and types before processing.

const Joi = require('joi');

const webhookSchema = Joi.object({
  id: Joi.string().required(),
  type: Joi.string().required(),
  amount: Joi.number().positive().required(),
  currency: Joi.string().length(3).required()
});

const { error } = webhookSchema.validate(req.body);
if (error) {
  return res.status(400).json({ error: 'Invalid payload' });
}

Additional Security Tips

  • Rate Limiting: Implement rate limits to prevent abuse and DDoS attacks
  • IP Whitelisting: Restrict endpoints to known provider IPs (Stripe, GitHub publish their IP ranges)
  • Secret Rotation: Change webhook secrets periodically and after security incidents
  • Logging & Monitoring: Log all webhook attempts and set up alerts for suspicious patterns
  • Environment Variables: Never hardcode secrets in source code - use env vars or secret managers

HookMetry Security:

HookMetry automatically validates signatures, logs all attempts (including failures), and provides real-time alerts for validation errors. See exactly which webhooks failed authentication and why.