Webhooks

Zamiast pollować /v1/review/{id}, możesz dostawać POST na swój URL, gdy moderator rozstrzygnie pozycję w kolejce, gdy zgłoszenia wyeskalują treść, albo — w trybie monitor — gdy model coś oflaguje. URL i sekret ustawisz w panelu.

Zdarzenia

event	Kiedy
`moderation.flagged`	Tryb `monitor`: model oflagował treść (`recommended_action` = block/review), choć nic nie zablokowaliśmy. Async „heads-up” dla shadow mode — w `review`/`enforce` decyzję masz już w odpowiedzi.
`review.resolved`	Moderator zaakceptował/odrzucił pozycję kolejki.
`report.escalated`	Liczba zgłoszeń przekroczyła próg — treść trafiła do kolejki.
`ping`	Test wysłany z panelu.

Format ładunku

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 niesie review_id, status, reference, reason, feedback (ocena trafności modelu) i resolver.

Weryfikacja podpisu

Policz HMAC-SHA256 z surowego body swoim sekretem i porównaj z nagłówkiem X-Modwall-Signature (czasowo-stałe porównanie).

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)

Odrzucaj żądania z niepasującym podpisem. Odpowiedz kodem 2xx — inny kod oznaczamy jako nieudane dostarczenie (widoczne w panelu). Dostarczanie jest asynchroniczne, z ponowieniami (backoff) w razie błędu lub odpowiedzi non-2xx.