Docs

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

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

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.