Verify a webhook signature

Anyone can find your webhook URL and POST a fake payload to it. Signature verification is how your server tells a genuine InsurGrid delivery apart from an imposter — before you trust a single field in the body.

New term — signature verification: recomputing a cryptographic fingerprint of an incoming request on your side, using a secret only you and the sender know, and checking it matches the one the sender attached. A match proves the request came from the sender and wasn't altered in transit.

This is the default auth scheme for every InsurGrid webhook (see Register your endpoint & choose an auth type if you've configured a different one — the rest of this page doesn't apply to those).

How it works

Every delivery carries an x-signature header: an HMAC-SHA256 of the raw request body, computed with your signing secret (from the API section — see Authentication & tokens), hex-encoded.

New term — HMAC-SHA256: a hashing algorithm that mixes a secret key into the fingerprint it produces. Recomputing the same hash of the same bytes with the same secret always yields the same output — so if your recomputed value matches the header, the request is genuine.

The check has three parts:

Get the exact raw bytes InsurGrid sent — not the parsed-and-re-serialized JSON.
Compute HMAC-SHA256(raw_body, signing_secret), hex-encoded.
Compare it to the x-signature header, using a timing-safe comparison. If it doesn't match, reject the request with 401.

⚠️ The raw-bytes footgun

The single most common first-time bug: computing the HMAC over JSON.stringify(parsedBody) (or Python's json.dumps(parsed)) instead of the bytes as received.

Parsing JSON and re-serializing it does not reliably reproduce the original bytes — key order, whitespace, and number formatting can all differ. Even a one-byte difference produces a completely different hash, so the check fails even though the request is perfectly genuine.

The fix: capture the raw body before your framework parses it, and hash those bytes — never the parsed object.

Verify it · server

Node (Express):

const crypto = require("crypto");
const express = require("express");
const app = express();

// Keep the raw body — you need the exact bytes to verify the signature.
app.use(express.json({
  verify: (req, _res, buf) => { req.rawBody = buf; },
}));

function verify(rawBody, signature, secret) {
  const expected = crypto.createHmac("sha256", secret).update(rawBody).digest("hex");
  const a = Buffer.from(expected, "hex");
  const b = Buffer.from(signature || "", "hex");
  // Lengths must match before timingSafeEqual — it throws on mismatched lengths.
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/hooks/insurgrid", (req, res) => {
  const ok = verify(req.rawBody, req.get("x-signature"), process.env.INSURGRID_SIGNING_SECRET);
  if (!ok) return res.sendStatus(401);   // not from InsurGrid — reject

  res.sendStatus(200);                   // acknowledge fast
  handle(req.body);                      // process after responding
});

Python (Flask):

import hmac, hashlib, os
from flask import Flask, request

app = Flask(__name__)

def verify(raw_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, signature or "")

@app.post("/hooks/insurgrid")
def insurgrid_hook():
    raw = request.get_data()                  # exact bytes — before any parsing
    signature = request.headers.get("x-signature", "")

    if not verify(raw, signature, os.environ["INSURGRID_SIGNING_SECRET"]):
        return "", 401                         # not from InsurGrid — reject

    handle(request.get_json())                 # parse only after verifying
    return "", 200                             # acknowledge fast

Notice both handlers read the raw body before parsing JSON, verify first, and only trust req.body / request.get_json() after the check passes.

Why timing-safe comparison

A plain expected === signature string comparison returns as soon as it finds the first mismatched character — which means it takes slightly longer to reject a guess that gets more characters right. An attacker who can measure that timing difference can, in theory, guess a valid signature one byte at a time. crypto.timingSafeEqual (Node) and hmac.compare_digest (Python) take the same amount of time regardless of where the mismatch is, closing that side channel. Always use them for this comparison instead of === or ==.

Reject on mismatch

If the signature doesn't match, return 401 and stop — don't process the body, don't log it as a near-miss with full contents, and don't fall back to trusting the request anyway. A mismatch means either the secret is wrong on one side (check you copied the current one) or the request isn't from InsurGrid.

Using a different scheme instead

If signature verification doesn't fit your setup, you can configure your endpoint to authenticate deliveries a different way — HMAC-SHA256 with your own secret, Basic auth, a bearer token, or a static API-key header. See Register your endpoint & choose an auth type for all five options and when each makes sense. A static credential is simpler to check but, unlike an HMAC, it doesn't prove the body wasn't altered in transit.

PreviousRegister your endpoint & choose an auth type

NextDelivery & de-duplication