Back to blog

Webhook Validation: Verify Signatures and Endpoints

Learn webhook validation with HMAC signatures, timestamp checks, and endpoint verification to secure incoming events and protect your app.

Introduction: What webhook validation means and why it matters

A webhook should never be trusted just because it reached your server. Webhook validation confirms that an incoming request really came from the expected sender and that its payload was not altered in transit. That protects both request authenticity and payload integrity before your app acts on the data.

The term also covers two related checks. First, there’s ongoing signature verification, where each webhook request is checked with a shared secret and an HMAC or similar signature scheme. Second, there’s subscription validation or endpoint setup, where a provider sends a challenge-response request to confirm that your webhook endpoint is real and ready to receive events.

This guide is for developers building webhook integrations in Node.js, Python, and other stacks who need a practical way to secure incoming events. You’ll see how to handle HMAC signatures, timestamp checks, secure comparison, and challenge-response flows without confusing validation with authentication or authorization. Authentication asks who sent the request; validation checks whether the request is genuine and intact; authorization decides what that sender is allowed to do.

Webhook validation vs authentication vs authorization

Webhook validation proves the message is genuine and unchanged. Authentication proves who sent it, often with a signature scheme that uses a shared secret. Authorization checks whether that sender is allowed to trigger the action you’re about to take.

Concept Purpose Example mechanism Typical failure mode
Validation Verify request authenticity and payload integrity HMAC signature check Tampered or replayed payload
Authentication Prove sender identity Shared secret, signature scheme Unknown or spoofed sender
Authorization Allow the action API key scopes, allowlist, role check Legit sender, wrong permission

HTTPS/TLS protects data in transit, but it does not replace webhook validation. A valid TLS connection can still carry a forged request if an attacker reaches your endpoint. Some providers also use challenge-response handshakes during setup; that confirms endpoint ownership, not ongoing message authenticity.

How webhook validation works

A provider sends a webhook request to your endpoint, and your app first inspects the signature header or a verification token before touching business logic. For signed deliveries, you verify the raw request body byte-for-byte against the expected HMAC or similar signature; for endpoint setup, you answer a challenge-response request to prove control of the URL, as documented in webhook endpoint setup.

The raw body matters because JSON parsing, whitespace changes, or re-serialization can change the bytes and break verification. That’s why canonicalization rules, timestamp validation, a nonce, or an event ID often appear in provider schemes: they reduce replay risk and bind the signature to one specific payload. If verification fails, reject the request; if it passes, route it to your handler after confirming the webhook payload structure.

What is HMAC webhook validation?

HMAC is a keyed hashing method: the provider combines the raw payload with a shared secret to produce a digest, and only someone who knows that secret can generate the same value. That makes HMAC a strong fit for webhook endpoint security because it helps prove both sender knowledge and payload integrity.

The usual flow is simple: the provider signs the exact bytes it sent, you recompute the digest from the request body you received, then compare your result to the signature header. If the values differ, the payload changed, the body was parsed incorrectly, or the request did not come from the expected sender.

Use SHA-256 when available; SHA-1 is legacy support only. Signature headers often include an algorithm prefix and an encoding such as hex or base64. GitHub’s X-Hub-Signature-256 follows this pattern: it carries an HMAC-SHA-256 digest, and your receiver should verify the raw payload with the shared secret, then compare the computed value to that header exactly.

How do you verify an X-Hub-Signature-256 header?

GitHub sends X-Hub-Signature-256 in the form sha256=<hex digest>. To verify it, compute an HMAC using SHA-256 over the raw request body and your shared secret, then compare the result to the header value using a constant-time comparison.

A correct verification flow looks like this:

  1. Read the raw request body before any JSON parser changes it.
  2. Compute HMAC-SHA-256(secret, rawBody).
  3. Prefix the digest with sha256= if the provider includes that format.
  4. Compare the expected value to X-Hub-Signature-256 with constant-time comparison.
  5. Reject the request if the signature is missing or does not match.

Validating endpoint challenge requests

Some platforms require subscription validation before they send real events. This is a one-time handshake that proves you control the webhook endpoint and can receive requests at that URL.

The flow is simple: the provider sends a validation request with a challenge token or code, your endpoint echoes it back exactly as documented, and the provider confirms the URL. Azure Event Grid uses this pattern during subscription setup, and Twilio-style validation flows work the same way for endpoint registration.

This challenge-response step does not replace ongoing webhook validation for later deliveries. Once the endpoint is verified, you still need signature checks on event requests. Response format, headers, and timing are strict, so follow each provider’s documentation closely.

How do I validate webhook requests in Node.js?

In Node.js, the key requirement is to read the raw body before any middleware parses it. In Express, use raw-body middleware for the webhook route, then verify the signature with the crypto module.

import express from "express";
import crypto from "crypto";

const app = express();

app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const secret = process.env.WEBHOOK_SECRET;
  const sig = req.get("X-Hub-Signature-256") || "";
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(req.body)
    .digest("hex");

  const a = Buffer.from(sig);
  const b = Buffer.from(expected);
  if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
    return res.sendStatus(401);
  }

  res.sendStatus(200);
});

If you need more control, place the verification in middleware so invalid requests stop before business logic runs. That pattern also works with other Node.js frameworks.

How do I validate webhook requests in Python?

In Python, use the raw request bytes and compare signatures with a constant-time helper from the standard library.

Flask

import hmac
import hashlib
from flask import request, abort

secret = b"your-secret"
sig = request.headers.get("X-Hub-Signature-256", "")
expected = "sha256=" + hmac.new(secret, request.data, hashlib.sha256).hexdigest()

if not hmac.compare_digest(sig, expected):
    abort(401)

FastAPI

import hmac
import hashlib
from fastapi import Request, HTTPException

async def verify_webhook(request: Request):
    secret = b"your-secret"
    sig = request.headers.get("X-Hub-Signature-256", "")
    body = await request.body()
    expected = "sha256=" + hmac.new(secret, body, hashlib.sha256).hexdigest()

    if not hmac.compare_digest(sig, expected):
        raise HTTPException(status_code=401, detail="Invalid signature")

Python’s hmac library and hashlib module are the standard tools here. The same approach applies to Ruby, PHP, and Go: verify the raw bytes, use the provider’s documented algorithm, and compare in constant time.

What is the difference between webhook validation and authentication?

The difference is scope. Validation checks whether the request is intact and trustworthy. Authentication checks who is making the request. In webhook systems, the same HMAC signature can support both ideas, but the operational goal is usually validation of the message rather than user login.

That distinction matters because a valid signature does not automatically mean the sender is authorized to trigger every action in your system. If your workflow has sensitive side effects, add authorization checks, idempotency controls, and event-type filtering after signature verification.

How do you securely compare webhook signatures?

Use constant-time comparison. Do not compare signatures with == or any method that can return early on the first mismatch.

In Node.js, use crypto.timingSafeEqual. In Python, use hmac.compare_digest. In other languages, use the platform’s constant-time comparison helper or a vetted library.

Also make sure both values are normalized to the same format before comparison. A hex digest is not the same as base64, and a prefixed header value such as sha256=... must be handled consistently.

What causes webhook signature mismatches?

Most signature mismatches come from a small set of production issues: the wrong secret, a body that changed before verification, the wrong hashing algorithm, or encoding differences between what the provider signed and what your app verifies. A common example is reading JSON into an object and re-serializing it before verification; that changes whitespace, key order, or escaping, so the signature no longer matches. Provider-specific formatting mistakes also show up often, such as signing a timestamped payload but verifying only the event body, or using the wrong header name or prefix.

Use a fixed troubleshooting sequence. First, confirm you deployed the exact secret for that environment and provider. Then inspect the exact signature header and compare the raw bytes you received with the bytes the provider says it signed; log the request ID, event ID, timestamp, and verification result, but never log the secret or full signature. Next, verify the timestamp window if the provider includes one, and check for clock drift on your server. Finish by confirming the algorithm and encoding: HMAC-SHA256 is not interchangeable with SHA1, hex is not base64, and UTF-8 handling must match the provider.

How do I prevent replay attacks on webhooks?

For replay protection, combine timestamp validation with a nonce, event ID tracking, and idempotent processing. A valid signature should still be rejected if the timestamp is stale or the event ID has already been processed. That blocks a replay attack even when an attacker captures a real delivery.

A practical pattern is:

  • Reject requests outside the allowed timestamp window.
  • Store the event ID or nonce for the retention period you need.
  • Make the handler idempotent so duplicate deliveries do not create duplicate side effects.
  • Keep the signature verification step separate from the business action so retries are safe.

Should I use IP allowlisting for webhook security?

IP allowlisting can reduce noise when a provider publishes stable source ranges, but it is brittle because those ranges can change and some providers route through multiple networks. It should complement, not replace, signature verification.

Use it only when the provider documents stable ranges and you can maintain them reliably. It is most useful as an additional control for high-risk endpoints, not as the primary trust mechanism.

Is HTTPS enough to secure webhook endpoints?

No. HTTPS and TLS protect data in transit, but they do not prove that the sender is legitimate or that the payload was not forged before it reached your server. You still need signature verification, secret rotation, logging, and monitoring.

Mutual TLS can add another trust layer when both sides support it, but it is still not a substitute for payload-level validation. Treat HTTPS as transport security, not message authentication.

How do I test webhook validation locally?

For local testing, use ngrok or the provider’s webhook testing tools to expose your endpoint and validate the exact raw request path you run in production. You can also replay captured requests against a local server to confirm that your middleware reads the raw body correctly.

A good local test plan includes:

  • Send a known-good signed request.
  • Send the same request after changing one byte in the body.
  • Send a request with a stale timestamp.
  • Send a request with a missing or malformed signature header.
  • Confirm your app returns the same status codes you expect in production.

What HTTP status code should I return for invalid webhooks?

Return 401 Unauthorized or 403 Forbidden for a bad signature, depending on your provider’s guidance and how you model the failure. Return 400 Bad Request for malformed requests, missing required headers, or payloads that cannot be parsed.

If the request is valid but your system cannot process it temporarily, return a 5xx response so the provider can retry. Do not return 200 for a failed validation check.

How do I troubleshoot webhook validation failures?

Start with the basics: confirm the secret, the header name, the algorithm, and the raw body. Then check whether middleware, proxies, or framework defaults are altering the request body before verification.

Useful troubleshooting steps:

  • Compare the exact bytes received with the provider’s sample payload.
  • Verify that the signature header format matches the provider’s documentation.
  • Check whether your app is parsing JSON before signature verification.
  • Confirm the timestamp window and server clock.
  • Review logs for repeated event IDs, which can indicate retries or replay attempts.

If the provider supports it, inspect delivery logs and request IDs on their side as well. That often reveals whether the failure is in your code, your environment, or the provider’s signing configuration.

What are the best practices for webhook validation in production?

Use the following production checklist:

  • Verify every request before business logic runs.
  • Read the raw request body and avoid canonicalization unless the provider explicitly requires it.
  • Use HMAC with SHA-256 when available; treat SHA-1 as legacy only.
  • Compare signatures with constant-time comparison.
  • Validate timestamps and reject stale requests.
  • Track event IDs or nonces to prevent replay attacks.
  • Make handlers idempotent.
  • Use HTTPS/TLS everywhere, and consider mutual TLS for high-trust integrations.
  • Use IP allowlisting only as a supplement.
  • Rotate shared secrets regularly and support overlapping secrets during secret rotation.
  • Log provider name, event ID, timestamp, and failure reason without exposing secrets or full payloads.
  • Monitor signature failures, malformed headers, and retry spikes.

For broader reliability guidance, see webhook reliability best practices and webhook tutorial.

Provider notes and implementation examples

Different providers use the same core ideas with different header names and setup flows.

  • GitHub: commonly uses X-Hub-Signature-256 with HMAC-SHA-256.
  • Azure Event Grid: uses subscription validation and challenge-response during endpoint setup.
  • Twilio: signs requests and may require additional request validation depending on the product.
  • Hookdeck: can sit in front of your endpoint to help with delivery reliability, retries, and observability.

Across stacks, the implementation pattern is the same: use the provider’s shared secret, verify the raw request body, compare in constant time, and keep validation separate from business logic.

Quick reference

  • Raw request body: verify the exact bytes, not parsed JSON.
  • Canonicalization: only use it if the provider explicitly defines it.
  • Signature header: read the documented header name and format.
  • Middleware: place validation before handlers.
  • Request authenticity: confirm the sender and message integrity.
  • Replay attack: block duplicates with timestamps, nonces, and event IDs.
  • TLS/HTTPS: protect transport, not message authenticity.
  • Secret rotation: support old and new secrets during rollout.