Webhooks

Statt zu pollen /v1/review/{id}, können Sie einen POST an Ihre URL erhalten, sobald ein Moderator einen Warteschlangeneintrag entscheidet, Meldungen einen Inhalt eskalieren oder — im Modus monitor — das Modell etwas markiert. URL und Geheimnis stellen Sie im Dashboard ein.

Ereignisse

event	Wann
`moderation.flagged`	Modus `monitor`: Das Modell hat den Inhalt markiert (`recommended_action` = block/review), obwohl wir nichts blockiert haben. Eine asynchrone Vorwarnung für den Shadow Mode — in `review`/`enforce` steht die Entscheidung bereits in der Antwort.
`review.resolved`	Ein Moderator hat einen Warteschlangeneintrag angenommen/abgelehnt.
`report.escalated`	Die Zahl der Meldungen hat die Schwelle überschritten — der Inhalt ging in die Warteschlange.
`ping`	Test aus dem Dashboard gesendet.

Format der Nutzlast

POST {twój_url}
Content-Type: application/json
X-Modwall-Event: moderation.flagged
X-Modwall-Signature: sha256=<hex>

{
  "event": "moderation.flagged",
  "data": {
    "reference": "post-123",
    "recommended": "block",
    "decision": "allow",
    "mode": "monitor",
    "scores": { "nsfw": 0.97, "safe": 0.03 },
    "threshold": 0.8,
    "model_version": "falconsai-int8-1"
  },
  "timestamp": "2026-06-27T12:00:00+00:00"
}

review.resolved enthält review_id, status, reference, reason, feedback (Bewertung der Modellgenauigkeit) und resolver.

Signaturprüfung

Berechnen Sie HMAC-SHA256 über den rohen Body mit Ihrem Geheimnis und vergleichen Sie das Ergebnis mit dem Header X-Modwall-Signature (zeitkonstanter Vergleich).

import hmac, hashlib

def valid(body: bytes, header: str, secret: str) -> bool:
    expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Weisen Sie Anfragen mit nicht passender Signatur ab. Antworten Sie mit einem 2xx-Code — jeder andere Code gilt als fehlgeschlagene Zustellung (im Dashboard sichtbar). Die Zustellung erfolgt asynchron, mit Wiederholungen (Backoff) bei Fehlern oder Nicht-2xx-Antworten.