Webhook-Signaturen mit HMAC-SHA-256 verifizieren
Information, keine Rechtsberatung. Diese Seite ist technische Referenz zur Verifikation von AI Act Radar Webhook-Signaturen. Compliance-Entscheidungen gehören in die Hand qualifizierter Anwältinnen und Anwälte.
AI Act Radar signiert jeden Webhook-Aufruf mit HMAC-SHA-256. Die Signatur wird über die Bytes <timestamp>.<raw_body> berechnet, mit dem geheimen Schlüssel, den Sie im Dashboard pro Subscription erzeugen. Empfänger müssen die Signatur in konstanter Zeit prüfen, den Zeitstempel auf 300 Sekunden Drift begrenzen und auf der Event-ID idempotent sein. Diese drei Regeln gelten plattformunabhängig: die Implementierung ist auf jeder gängigen Runtime weniger als 50 Zeilen.
Header, die jeder Webhook trägt
X-AIA-Timestamp: Unix-Sekunden zum Zeitpunkt der Auslieferung. Drift > 300 Sekunden = ablehnen.X-AIA-Signature: Formatsha256=<hex>, HMAC-SHA-256 über<timestamp>.<raw_body>.X-AIA-Event-Id: Globale Event-ID. Verwenden Sie diese für Ihre Idempotenz-Tabelle.X-AIA-Delivery-Id: Auslieferungs-ID. Dieselbe Event-ID kann mehrfach geliefert werden (Retry).
Python: hmac aus der Standard-Bibliothek
import hmac, hashlib, time
def verify(raw_body: bytes, ts: str, sig_header: str, secret: str) -> bool:
if not ts or not sig_header:
return False
try:
if abs(int(time.time()) - int(ts)) > 300:
return False
except ValueError:
return False
provided = sig_header.removeprefix("sha256=")
expected = hmac.new(secret.encode(), f"{ts}.".encode() + raw_body,
hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, provided)
Wichtig: raw_body ist die Byte-Repräsentation des unverarbeiteten Request-Bodies. Nicht das Resultat von request.json(). Frameworks wie Flask oder FastAPI liefern den Rohbody über request.get_data() bzw. request.body.
Node: crypto.timingSafeEqual
import crypto from 'node:crypto';
export function verify(rawBody: string, ts: string, sigHeader: string, secret: string): boolean {
if (!ts || !sigHeader) return false;
const tsNum = Number(ts);
if (!Number.isFinite(tsNum)) return false;
if (Math.abs(Date.now() / 1000 - tsNum) > 300) return false;
const provided = sigHeader.startsWith('sha256=') ? sigHeader.slice(7) : sigHeader;
const expected = crypto
.createHmac('sha256', secret)
.update(`${ts}.${rawBody}`)
.digest('hex');
if (expected.length !== provided.length) return false;
return crypto.timingSafeEqual(
Buffer.from(expected, 'hex'),
Buffer.from(provided, 'hex'),
);
}
Go: crypto/hmac
func Verify(rawBody []byte, ts, sigHeader, secret string) bool {
tsNum, err := strconv.ParseInt(ts, 10, 64)
if err != nil {
return false
}
if abs(time.Now().Unix()-tsNum) > 300 {
return false
}
provided := strings.TrimPrefix(sigHeader, "sha256=")
mac := hmac.New(sha256.New, []byte(secret))
mac.Write([]byte(ts))
mac.Write([]byte("."))
mac.Write(rawBody)
expected := hex.EncodeToString(mac.Sum(nil))
return hmac.Equal([]byte(expected), []byte(provided))
}
Häufige Fehler
- JSON statt Rohbytes signieren. Wenn Ihr Framework den Body parst und neu serialisiert, ändert sich Whitespace und damit der HMAC. Immer den Rohbody erfassen.
- Stringvergleich mit
==. Macht Sie für Timing-Angriffe verwundbar. Immercompare_digest,timingSafeEqual,hmac.Equal. - Zeitstempel-Drift ignorieren. Ohne Drift-Check bleibt eine abgefangene Signatur unbegrenzt gültig: Replay-Angriff.
- Gleicher Secret-Wert auf mehreren Subscriptions. Pro Subscription einen eigenen Secret erzeugen; rotieren Sie alle 90 Tage.
Live-Test gegen Ihren eigenen Endpoint
Im Dashboard finden Sie einen "Test delivery"-Button, der ein signiertes Beispiel-Event an Ihre Subscription-URL sendet. Die Auslieferungshistorie zeigt Antwortcode und Drift, sodass Sie sofort sehen, ob Ihre Verifikation korrekt arbeitet.
Verwandte Themen
AI Act Radar wird betrieben von ligea GmbH, Karlsruhe. Information, keine Rechtsberatung.