HMAC-SHA256 webhook signature verification: Python, Node, Go reference
Information only, not legal advice. This page is engineering reference material for verifying AI Act Radar webhook signatures. Confirm any compliance decision with qualified counsel.
AI Act Radar signs every webhook delivery with HMAC-SHA256 over the raw request body and a timestamp. Verification is mandatory: unsigned or stale deliveries must be rejected. This page is a cross-language reference for doing it correctly, with constant-time comparison and a replay window.
Header format
Each delivery carries two headers:
X-AIAR-Timestamp: Unix epoch seconds at the moment of signing.X-AIAR-Signature: the literal stringv1=followed by a hex-encoded HMAC-SHA256.
The signed payload is the concatenation <timestamp> + "." + <raw_body>. The raw body is the byte sequence as received: do not re-serialise the JSON before verifying.
Verification algorithm
- Reject the request if either header is missing.
- Reject if the timestamp is more than 300 seconds away from server time (replay window).
- Compute HMAC-SHA256 over
timestamp + "." + raw_bodywith the subscription secret as the key. - Hex-encode and prefix with
v1=. - Compare to
X-AIAR-Signatureusing a constant-time comparison. - Only after the signature passes, parse the JSON.
Python: Flask
import hmac
import hashlib
import time
from flask import Flask, request, abort
app = Flask(__name__)
SECRET = b"whsec_REPLACE_ME"
TOLERANCE_SECONDS = 300
@app.post("/webhooks/aiar")
def receive():
ts = request.headers.get("X-AIAR-Timestamp", "")
sig = request.headers.get("X-AIAR-Signature", "")
if not ts or not sig:
abort(400, "missing signature headers")
try:
ts_int = int(ts)
except ValueError:
abort(400, "bad timestamp")
if abs(int(time.time()) - ts_int) > TOLERANCE_SECONDS:
abort(400, "stale timestamp")
raw = request.get_data() # bytes, untouched
signed = ts.encode("utf-8") + b"." + raw
expected = "v1=" + hmac.new(SECRET, signed, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, sig):
abort(401, "bad signature")
event = request.get_json(force=True)
# process event...
return ("", 204) Node: Express
import express from "express";
import crypto from "node:crypto";
const app = express();
const SECRET = "whsec_REPLACE_ME";
const TOLERANCE_SECONDS = 300;
// IMPORTANT: capture the raw body before any JSON parser touches it.
app.post(
"/webhooks/aiar",
express.raw({ type: "application/json" }),
(req, res) => {
const ts = req.header("x-aiar-timestamp");
const sig = req.header("x-aiar-signature");
if (!ts || !sig) return res.status(400).send("missing signature headers");
const tsInt = Number.parseInt(ts, 10);
if (Number.isNaN(tsInt)) return res.status(400).send("bad timestamp");
const now = Math.floor(Date.now() / 1000);
if (Math.abs(now - tsInt) > TOLERANCE_SECONDS) {
return res.status(400).send("stale timestamp");
}
const signed = Buffer.concat([
Buffer.from(ts + "."),
req.body, // raw Buffer
]);
const expected =
"v1=" + crypto.createHmac("sha256", SECRET).update(signed).digest("hex");
const a = Buffer.from(expected);
const b = Buffer.from(sig);
if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
return res.status(401).send("bad signature");
}
const event = JSON.parse(req.body.toString("utf8"));
// process event...
res.status(204).end();
}
); Go: net/http
package main
import (
"crypto/hmac"
"crypto/sha256"
"encoding/hex"
"io"
"net/http"
"strconv"
"time"
)
const (
secret = "whsec_REPLACE_ME"
tolerance = 300 * time.Second
)
func receive(w http.ResponseWriter, r *http.Request) {
ts := r.Header.Get("X-AIAR-Timestamp")
sig := r.Header.Get("X-AIAR-Signature")
if ts == "" || sig == "" {
http.Error(w, "missing signature headers", http.StatusBadRequest)
return
}
tsInt, err := strconv.ParseInt(ts, 10, 64)
if err != nil {
http.Error(w, "bad timestamp", http.StatusBadRequest)
return
}
if d := time.Since(time.Unix(tsInt, 0)); d < -tolerance || d > tolerance {
http.Error(w, "stale timestamp", http.StatusBadRequest)
return
}
raw, err := io.ReadAll(r.Body)
if err != nil {
http.Error(w, "read error", http.StatusBadRequest)
return
}
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts))
mac.Write([]byte("."))
mac.Write(raw)
expected := "v1=" + hex.EncodeToString(mac.Sum(nil))
if !hmac.Equal([]byte(expected), []byte(sig)) {
http.Error(w, "bad signature", http.StatusUnauthorized)
return
}
// parse and process raw...
w.WriteHeader(http.StatusNoContent)
}
func main() {
http.HandleFunc("/webhooks/aiar", receive)
_ = http.ListenAndServe(":8080", nil)
} Common mistakes
- Comparing strings with
==leaks length and prefix information through timing. Use the constant-time helper of the language. - Re-serialising the body before signing. The HMAC is over bytes as delivered; any whitespace or key-order change breaks the signature.
- Skipping the timestamp check. Without it the signature is replayable indefinitely.
- Storing the secret in source. Inject from a secret manager; rotate via the subscription endpoint.
- Returning 200 for invalid signatures. Return 4xx so the sender does not record a successful delivery.
→ See live updates: https://aiactradar.com
→ Subscribe to webhook: https://docs.aiactradar.com/quickstart