Webhooks¶

Real-Time-Push statt Polling. Statt periodisch die API abzufragen, sagen Sie MailGuard „melde dich bei meinem Endpoint, wenn X passiert".

Konfiguration¶

Im Admin-UI unter Settings → Webhooks (im API-Keys-Tab) — pro Webhook:

URL — wohin POST gesendet wird (HTTPS empfohlen)
Secret — geheimes HMAC-Token für Signatur-Validierung
Events — welche Event-Typen abonniert werden

Event-Typen¶

Event	Trigger
`quarantine.added`	Mail in Quarantäne gelandet
`quarantine.released`	Mail freigegeben (Operator oder End-User)
`quarantine.discarded`	Mail verworfen
`reputation.threshold_crossed`	Sender-IP-Reputation hat eine Schwelle über/unterschritten
`license.changed`	Tier-Wechsel oder Lizenz-Refresh
`cluster.node_joined`	Neuer Node ist dem Cluster beigetreten
`cluster.node_left`	Node hat den Cluster verlassen
`dkim.rotation_due`	DKIM-Schlüssel-Rotation steht an (30 Tage Vorwarnung)
`cert.expiring`	TLS-Zertifikat läuft demnächst ab

Payload-Format¶

{
  "event": "quarantine.added",
  "timestamp": "2026-05-01T08:42:13Z",
  "node_id": "node-1",
  "data": {
    "queue_id": "4F2A8C0D",
    "sender": "noreply@phisher.tk",
    "recipients": ["alice@example.com"],
    "score": 14.7,
    "reason": "phishing"
  }
}

HMAC-Signatur¶

Jede Webhook-POST hat einen Header:

X-MailGuard-Signature: sha256=<hex-digest>

Berechnet als HMAC-SHA256(secret, request_body). Empfänger muss validieren — Beispiel-Code:

import hmac, hashlib

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

Retry-Verhalten¶

Bei Empfänger-HTTP-5xx oder Timeout retryt MailGuard mit exponential Backoff: nach 30 s, dann 2 min, 10 min, 1 h, 6 h. Max 5 Versuche. 4xx-Fehler werden nicht retryed (Empfänger-Konfigurationsproblem).

Delivery-Guarantee¶

At-least-once. Empfänger muss Idempotenz selbst sicherstellen — typisch über Event-ID-Tracking.