securitywebhooks

Webhook security best practices

April 28, 2026 · 5 min read

Webhooks are HTTP callbacks sent from one system to yours. They carry real business events — payments, order updates, user signups. If an attacker can forge a webhook, they can trigger your business logic with fake data. Here is how to prevent that.

1. Always verify the signature

Every HookSync delivery includes a X-Webhook-Signature header. The value is sha256=<hex>— an HMAC-SHA256 of the raw request body using your endpoint's secret.

import crypto from 'node:crypto';

function verifySignature(rawBody: string, header: string, secret: string): boolean {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(rawBody, 'utf8')
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(header),
    Buffer.from(expected),
  );
}

Use timingSafeEqual — not string equality. String equality short-circuits on the first differing byte and leaks timing information that attackers can use to brute-force the signature.

2. Prevent replay attacks

A signature alone is not enough. An attacker who captures a valid signed request can replay it later — triggering the same order fulfillment twice, for example. HookSync includes a X-Webhook-Timestamp header. Check that the timestamp is within a 5-minute window:

const timestamp = parseInt(req.headers['x-webhook-timestamp'], 10);
const age = Date.now() / 1000 - timestamp;
if (age > 300 || age < -60) {
  res.status(400).json({ error: 'Stale webhook' });
  return;
}

3. Use HTTPS-only endpoints

Never accept webhooks over plain HTTP in production. The signature prevents tampering but not interception. HookSync will still deliver to HTTP endpoints (useful for local dev), but for production, enforce HTTPS and verify the TLS certificate.

4. Return 2xx quickly, process asynchronously

HookSync waits up to 30 seconds for your endpoint to respond. If you process the event synchronously during the request, a slow database query can cause a timeout, which HookSync treats as a failure and retries. Instead: acknowledge immediately, enqueue for background processing.

app.post('/webhooks/hooksync', (req, res) => {
  if (!verifySignature(req.rawBody, req.headers['x-webhook-signature'], SECRET)) {
    return res.status(401).end();
  }
  queue.push({ event: req.body }); // enqueue first
  res.status(200).end();           // then respond
});

5. Handle idempotency

HookSync may deliver the same event more than once — on retry after a network error where your endpoint processed the event but the response was lost. Use the event ID to deduplicate: if you have already processed event id, acknowledge the second delivery without re-processing.

← back to blog