Webhooks

Webhooks ermöglichen es VisitorFilters, Echtzeit-Benachrichtigungen an Ihren Server zu senden, wenn bestimmte Ereignisse eintreten. Dies ermöglicht die Integration mit Ihrer bestehenden Infrastruktur, dem Incident-Management oder benutzerdefinierter Automatisierung.

Webhooks einrichten

Gehen Sie zu Websites → [Ihre Website] → Webhooks
Klicken Sie auf Endpunkt hinzufügen
Geben Sie Ihre Endpunkt-URL ein (muss HTTPS sein)
Wählen Sie die Ereignisse aus, die Sie empfangen möchten
Speichern — Sie erhalten ein Signiergeheimnis

Verfügbare Ereignisse

Ereignis	Auslöser
`visitor.blocked`	Ein Besucher wurde durch eine Regel blockiert
`visitor.challenged`	Einem Besucher wurde eine Challenge angezeigt
`ban.created`	Eine neue Sperre wurde hinzugefügt (manuell oder automatisch)
`ban.expired`	Eine Sperre ist abgelaufen oder wurde aufgehoben
`anomaly.detected`	Risikobewertung hat Schwellenwert überschritten
`rate_limit.exceeded`	Ein Besucher hat Rate-Limits überschritten

Nutzlastformat

Alle Webhook-Nutzlasten folgen einer einheitlichen Struktur:

{
  "id": "evt_abc123",
  "type": "visitor.blocked",
  "timestamp": "2025-05-22T14:30:00Z",
  "site_id": "site_xyz",
  "data": {
    "visitor_ip": "203.0.113.42",
    "country": "CN",
    "rule_id": "rule_456",
    "action": "block",
    "reason": "Geo block: CN"
  }
}

Signaturverifizierung

Jede Webhook-Anfrage enthält einen X-VF-Signature-Header mit einer HMAC-SHA256-Signatur. Verifizieren Sie diese, um sicherzustellen, dass die Nutzlast von VisitorFilters stammt:

$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhookSecret);

if (! hash_equals($signature, $_SERVER['HTTP_X_VF_SIGNATURE'])) {
    http_response_code(401);
    exit;
}

Wiederholungsrichtlinie

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt, wiederholen wir die Zustellung:

1. Wiederholung: 30 Sekunden
2. Wiederholung: 5 Minuten
3. Wiederholung: 30 Minuten
4. Wiederholung: 2 Stunden
5. Wiederholung: 24 Stunden

Nach 5 fehlgeschlagenen Versuchen wird die Zustellung als fehlgeschlagen markiert. Sie können die Zustellung manuell über das Dashboard erneut versuchen.

Beste Praktiken

Antworten Sie schnell mit 200 OK — verarbeiten Sie die Nutzlast asynchron, falls nötig.
Verifizieren Sie immer die Signatur vor der Verarbeitung.
Verwenden Sie Idempotenz — Webhooks können mehr als einmal zugestellt werden.
Überwachen Sie den Zustand Ihres Endpunkts unter Webhooks → Zustellungen.