Webhook Security: How to Verify Incoming Requests with HMAC Signatures

If you've ever integrated a payment provider, GitHub Actions, or a third-party API that sends you events, you've used webhooks. And if you've ever worried about whether the request actually came from who it claims — or whether someone could forge one — you've run into the webhook security problem.

The solution is HMAC verification. Here's how it works and how to implement it.

The problem with unauthenticated webhooks

Without verification, anyone who discovers your webhook endpoint URL can send requests pretending to be your payment processor or CI/CD system. Your server has no way to distinguish:

• A real payment notification from Stripe
• A fake request crafted by an attacker to trigger order fulfilment

This is not theoretical. Webhook forgery has been used to trigger payouts, bypass authorization gates, and flood processing queues.

HMAC: a shared secret approach

HMAC (Hash-based Message Authentication Code) solves this with a shared secret. The flow works like this:

1. When you register a webhook with the provider, they give you a secret key (or you set one)
2. When the provider sends an event, they compute: HMAC-SHA256(secret_key, request_body)
3. They include the signature in a request header (e.g. X-Hub-Signature-256, Stripe-Signature)
4. You recompute the HMAC on your end and compare
5. If they match, the request is authentic — only someone with the secret key could produce that signature

The body hasn't been encrypted — anyone can read it. But the signature proves it wasn't tampered with after signing.

Reading the signature header

Different providers use different header formats:

GitHub:

X-Hub-Signature-256: sha256=abc123...

Strip the sha256= prefix before comparing.

Stripe:

Stripe-Signature: t=1745488800,v1=abc123...,v1=def456...

Stripe includes a timestamp to prevent replay attacks. The signed payload is timestamp.body, not just the body.

Slack:

X-Slack-Signature: v0=abc123...

The signed payload is v0:timestamp:body.

Always check the provider's documentation — the details matter.

Implementation in Node.js

const crypto = require('crypto');

function verifyWebhook(secret, body, signature) {
  // body must be the raw Buffer — do not parse JSON first
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');

  const expected = `sha256=${hmac}`;

  // Use timingSafeEqual to prevent timing attacks
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// Express handler
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-hub-signature-256'];

  if (!verifyWebhook(process.env.WEBHOOK_SECRET, req.body, signature)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(req.body);
  // handle event...
  res.sendStatus(200);
});

Key points:

• Use express.raw(), not express.json() — you need the raw body bytes, not the parsed object. HMAC is computed over the exact bytes received.
• Use crypto.timingSafeEqual() — regular string comparison (===) is vulnerable to timing attacks where an attacker can infer matching bytes by measuring how long comparisons take.

Implementation in Python (FastAPI)

import hmac
import hashlib

def verify_webhook(secret: str, body: bytes, signature: str) -> bool:
    expected = hmac.new(
        secret.encode(),
        body,
        hashlib.sha256
    ).hexdigest()
    expected = f"sha256={expected}"

    # hmac.compare_digest is the timing-safe equivalent
    return hmac.compare_digest(signature, expected)

@app.post("/webhook")
async def webhook(request: Request):
    body = await request.body()
    signature = request.headers.get("X-Hub-Signature-256", "")

    if not verify_webhook(os.environ["WEBHOOK_SECRET"], body, signature):
        raise HTTPException(status_code=401, detail="Invalid signature")

    event = json.loads(body)
    # handle event...
    return {"status": "ok"}

Replay attacks and timestamps

HMAC verification proves the request is authentic — but not that it's recent. An attacker could capture a valid request and replay it 10 minutes later. The solution is timestamps:

1. The provider includes the current timestamp in the signed payload or header
2. You check that the timestamp is within an acceptable window (Stripe uses 5 minutes)

function verifyStripeWebhook(secret, body, header) {
  const parts = header.split(',').reduce((acc, part) => {
    const [key, val] = part.split('=');
    acc[key] = val;
    return acc;
  }, {});

  const timestamp = parts['t'];
  const signatures = header.match(/v1=([a-f0-9]+)/g) || [];

  // Check timestamp is within 5 minutes
  const age = Math.floor(Date.now() / 1000) - parseInt(timestamp);
  if (age > 300) throw new Error('Webhook too old — possible replay attack');

  const signedPayload = `${timestamp}.${body}`;
  const hmac = crypto
    .createHmac('sha256', secret)
    .update(signedPayload)
    .digest('hex');

  return signatures.some(sig => {
    const provided = sig.replace('v1=', '');
    return crypto.timingSafeEqual(
      Buffer.from(hmac),
      Buffer.from(provided)
    );
  });
}

Testing your HMAC logic

Before deploying, test the signature verification offline. You can compute HMAC-SHA256 for any string in your browser using the SnappyTools Hash Generator — enter the text, select SHA-256, and check that the output matches what your verification code produces for the same input.

Common mistakes

Parsing JSON before verifying — once you JSON.parse() the body, the byte order and whitespace may change. Always verify the raw bytes.

Using string comparison instead of timing-safe comparison — regular === leaks timing information. Always use crypto.timingSafeEqual (Node) or hmac.compare_digest (Python).

Not checking timestamps — HMAC alone is not enough if you don't reject old requests.

Storing secrets in code — webhook secrets belong in environment variables, not hardcoded strings. Rotate them if they leak.

---

HMAC webhook verification is one of the few security patterns you can implement correctly in under 20 lines of code. Once you understand the flow — raw body, shared secret, timing-safe comparison, optional timestamp check — you can apply it consistently across every provider that uses it.