Implementing HMAC Signature Verification for Inbound Webhooks

· 7 min read ·
Implementing HMAC Signature Verification for Inbound Webhooks

What You’ll Need

Table of Contents

Understanding HMAC Signatures for Webhook Security

Every public HTTP endpoint receiving webhook data faces three core security risks: unauthorized senders spoofing requests, middleboxes altering request payloads, and malicious actors intercepting valid payloads to re-send them in replay attacks. Standard API key authentication sent via headers offers limited protection. If an attacker gains access to the stream, they can capture the header and re-use it indefinitely.

Hash-based Message Authentication Code (HMAC) solves these problems simultaneously. Instead of transmitting a static secret over the wire, both the sender and the receiver share a secret key. When an event triggers on the sender system, it hashes the raw HTTP request body together with the secret key using a cryptographic algorithm like SHA-256. The resulting string is sent inside a header, commonly named X-Hub-Signature-256 or X-Signature.

When your application receives the request, it recalculates the hash using its local copy of the secret key and compares it against the signature provided in the header. If even a single byte of the payload changed during transit, the generated hash will not match, and your system can reject the request with an HTTP 401 Unauthorized status. This architecture works exceptionally well when self-hosting open source tools on budget VPS infrastructure without paying per-execution API pricing.

Three technical rules govern secure HMAC implementation:

  1. You must hash the exact, unparsed raw bytes of the incoming request body.
  2. You must compare the resulting signature using constant-time string comparison algorithms to eliminate timing attacks.
  3. You must enforce timestamp windows to render captured signatures useless after a short time window.

Building a Secure Express Webhook Receiver with HMAC

A major failure point in Node.js webhook verification happens when developers parse the HTTP body into a JavaScript object using express.json() before computing the signature. JSON parsers alter whitespace, key ordering, and character encodings. Even a minor reformatting will cause signature recalculation to fail.

To retain the exact payload bytes, you must capture the raw buffer during request parsing. Spin up an instance on Hetzner VPS or DigitalOcean and install Node.js.

Here is a full Node.js and Express server implementation that captures raw request buffers, calculates HMAC SHA-256 signatures, and verifies incoming webhooks safely.

const express = require('express');
const crypto = require('crypto');

const app = express();
const PORT = 3000;
const WEBHOOK_SECRET = 'super-secret-key-change-this-in-production-7f8a';

app.use(express.json({
  verify: (req, res, buf, encoding) => {
    req.rawBody = buf;
  }
}));

function verifyHmacSignature(req) {
  const signatureHeader = req.headers['x-signature-256'];
  if (!signatureHeader) {
    return false;
  }

  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(req.rawBody)
    .digest('hex');

  const providedSignature = signatureHeader.replace(/^sha256=/, '');

  const expectedBuffer = Buffer.from(expectedSignature, 'utf8');
  const providedBuffer = Buffer.from(providedSignature, 'utf8');

  if (expectedBuffer.length !== providedBuffer.length) {
    return false;
  }

  return crypto.timingSafeEqual(expectedBuffer, providedBuffer);
}

app.post('/webhook', (req, res) => {
  if (!req.rawBody) {
    return res.status(400).send('Missing request body');
  }

  const isValid = verifyHmacSignature(req);

  if (!isValid) {
    console.warn('Rejected invalid HMAC webhook attempt');
    return res.status(401).json({ status: 'error', message: 'Invalid signature' });
  }

  console.log('Webhook payload verified successfully:', req.body);
  return res.status(200).json({ status: 'success', received: true });
});

app.listen(PORT, () => {
  console.log(`Webhook server listening on port ${PORT}`);
});

The key function here is crypto.timingSafeEqual. Standard string comparisons using === return false instantly as soon as a character mismatch occurs. Attackers measure response times across thousands of requests to deduce the signature character by character. Constant-time comparison guarantees that the execution time remains identical regardless of where the mismatch occurs.

💡 Fast-Track Your Project: Don’t want to configure this yourself? I build custom n8n pipelines and bots. Message me with code SYS3-HUGO.

Implementing HMAC Verification in n8n Workflows

When using workflow engines like n8n Cloud or self-hosted instances, incoming HTTP Webhook nodes automatically parse incoming requests. While this convenience simplifies node mapping, you must ensure the node exposes the raw body options or process the raw header and stringified body within a dedicated Code node.

If you are evaluating orchestration tools, Make.com offers built-in webhook features, but n8n gives you complete execution access to Native Node.js modules like crypto directly inside its workflow runtime.

Below is a complete, fully executable JavaScript block designed for an n8n Code Node placed immediately after a Webhook Node configured to output raw body data.

const crypto = require('crypto');

const items = $input.all();
const results = [];

const WEBHOOK_SECRET = 'my-n8n-production-hmac-secret-9012';

for (const item of items) {
  const headers = item.json.headers || {};
  const rawBodyString = item.json.rawBody || JSON.stringify(item.json.body);
  
  const signatureHeader = headers['x-hub-signature-256'] || headers['x-signature'] || '';
  const cleanSignature = signatureHeader.replace(/^sha256=/, '');

  if (!cleanSignature) {
    results.push({
      json: {
        verified: false,
        error: 'Missing signature header'
      }
    });
    continue;
  }

  const computedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(rawBodyString, 'utf8')
    .digest('hex');

  const computedBuf = Buffer.from(computedSignature, 'utf8');
  const providedBuf = Buffer.from(cleanSignature, 'utf8');

  let isValid = false;
  if (computedBuf.length === providedBuf.length) {
    isValid = crypto.timingSafeEqual(computedBuf, providedBuf);
  }

  results.push({
    json: {
      verified: isValid,
      payload: item.json.body,
      processedAt: new Date().toISOString()
    }
  });
}

return results;

To run this in n8n, ensure your WEBHOOK_SECRET environment variable or n8n secret manager is injected properly. If verified evaluates to false, route the workflow execution directly to a Stop and Error node to halt processing immediately.

Python FastAPI HMAC Verification with Timing Attack Mitigation

Python applications built on asynchronous frameworks like FastAPI require reading the raw byte stream directly off the underlying request object before pydantic serialization happens.

In addition to HMAC calculation, this Python example enforces a strict timestamp tolerance window. Senders include a UNIX timestamp in a custom header like X-Signature-Timestamp. If the time difference between server time and header timestamp exceeds 300 seconds, the request is dropped to stop replay attacks.

If you want to run your verification services cheaply alongside your database, check out how I run 3 automated systems on a single $7/Month VPS on providers like Contabo VPS.

Here is the complete Python production script using secrets.compare_digest:

import hmac
import hashlib
import time
from fastapi import FastAPI, Request, HTTPException, status
import uvicorn

app = FastAPI()

WEBHOOK_SECRET = b"production-python-secret-key-3345"
MAX_ALLOWED_DRIFT_SECONDS = 300

def verify_signature(raw_body: bytes, signature_header: str) -> bool:
    if signature_header.startswith("sha256="):
        signature_header = signature_header[7:]

    computed_hmac = hmac.new(
        WEBHOOK_SECRET,
        msg=raw_body,
        digestmod=hashlib.sha256
    ).hexdigest()

    return hmac.compare_digest(computed_hmac, signature_header)

@app.post("/api/v1/webhooks")
async def handle_incoming_webhook(request: Request):
    signature_header = request.headers.get("X-Signature-256")
    timestamp_header = request.headers.get("X-Signature-Timestamp")

    if not signature_header or not timestamp_header:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Missing security headers"
        )

    try:
        request_time = int(timestamp_header)
    except ValueError:
        raise HTTPException(
            status_code=status.HTTP_400_BAD_REQUEST,
            detail="Invalid timestamp format"
        )

    current_time = int(time.time())
    if abs(current_time - request_time) > MAX_ALLOWED_DRIFT_SECONDS:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="Request timestamp outside acceptable tolerance window"
        )

    raw_body = await request.body()

    is_valid = verify_signature(raw_body, signature_header)
    if not is_valid:
        raise HTTPException(
            status_code=status.HTTP_401_UNAUTHORIZED,
            detail="HMAC verification failed"
        )

    payload = await request.json()
    return {"status": "accepted", "data": payload}

if __name__ == "__main__":
    uvicorn.run(app, host="0.0.0.0", port=8000)

Edge Hardening and Drift Management

Securing your application code is only half the battle. Your deployment environment must also enforce strict TLS standards to prevent man-in-the-middle manipulation of headers before they reach your code.

When forwarding traffic to your webhook endpoints, make sure you’re configuring Nginx reverse proxy with Certbot SSL to encrypt payload data in transit and manage certificate renewals automatically. You can point your DNS records from Namecheap straight to your reverse proxy IP address.

To further defend your HMAC verification endpoints against Distributed Denial of Service (DDoS) and brute force attempts, configure rate limiting directly in your Nginx configuration.

Here is a robust Nginx server block configuration that limits webhook requests to 10 per second per IP address while passing the raw headers cleanly:

limit_req_zone $binary_remote_addr zone=webhook_limit:10m rate=10r/s;

server {
    listen 443 ssl http2;
    server_name webhooks.yourdomain.com;

    ssl_certificate /etc/letsencrypt/live/webhooks.yourdomain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/webhooks.yourdomain.com/privkey.pem;

    location /webhook {
        limit_req zone=webhook_limit burst=20 nodelay;

        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;

        proxy_pass_request_headers on;
        proxy_buffering off;
    }
}

By enforcing SSL at the reverse proxy level, stripping unneeded whitespace, capping execution bursts, using raw byte body parsing, and validating timing-safe HMAC algorithms in your web application, your webhook integration will remain secure against spoofing, tampered data, and timing side-channel attacks.

Getting Started

To implement production-grade webhook security today, spin up your hosting infrastructure, register your domain endpoints, and test your handlers thoroughly:

Outsource Your Automation

Don’t have time? I build production n8n workflows, WhatsApp bots, and fully automated YouTube Shorts pipelines. Hire me on Fiverr, mention SYS3-HUGO for priority. Or DM at chasebot.online.

Want to automate this yourself?

Start with n8n Cloud (free tier available) or self-host on a Hetzner VPS for full control.

Want this engine running on your own VPS?

This blog publishes itself — daily, unattended, on free API tiers. The full engine, Hugo theme, and setup guide are available as System 3.

Get System 3

Related Guides

system online