Verifying Nessie v2 webhook HMAC in Python/FastAPI: key is the whole 'whsec_...' string, message is b't.' + raw body; FastAPI Header() naming is not the problem
Checked against a real hosted delivery from Nessie v2 (v2-prod-api.nessieisreal.com), Nov 2026, to settle three questions that cost time while debugging a FastAPI receiver.
1. The HMAC key is the secret exactly as POST /webhooks returned it, including the whsec_ prefix. Do not strip the prefix or base64-decode it. The secret is shown only once at creation (or on POST /webhooks/{id}/secret/rotate), so save it then.
2. The signed message is the timestamp, a dot, then the raw request bytes. Header format: Nessie-Signature: t=<unix seconds>,v1=<hex>. This reproduced the delivered v1 value exactly:
import hmac, hashlib, time def verify(secret: str, header: str, body: bytes, tolerance=300) -> bool: parts = dict(p.split("=", 1) for p in header.split(",")) if abs(time.time() - int(parts["t"])) > tolerance: return False mac = hmac.new(secret.encode(), parts["t"].encode() + b"." + body, hashlib.sha256).hexdigest() return hmac.compare_digest(mac, parts["v1"])
In FastAPI read the bytes with body = await request.body() before any parsing. Do not declare a Pydantic model parameter for the payload and then re-serialize it with json.dumps: key order and whitespace change and the HMAC no longer matches.
3. FastAPI's Header() is fine. async def hook(request: Request, nessie_signature: str | None = Header(None)) binds to the Nessie-Signature header, because FastAPI converts underscores to hyphens and header lookup is case-insensitive. If your receiver answers 400 "missing headers", the likely cause is that you also required a Nessie-Event-Id header, which hosted deliveries do not send (the event id is body["id"]).
During secret rotation, try every currently valid secret and accept if any matches. Return 2xx quickly (store, then process) because deliveries are at least once with retries. Debug with GET /webhooks/{id}/deliveries: http_status 401 there means your signature check rejected Nessie's request.