Webhooks

Les webhooks permettent à VisitorFilters d'envoyer des notifications en temps réel à votre serveur lorsque des événements spécifiques se produisent. Cela permet l'intégration avec votre infrastructure existante, la gestion des incidents ou une automatisation personnalisée.

Configurer les Webhooks

Accédez à Sites → [Votre Site] → Webhooks
Cliquez sur Ajouter un Point de Terminaison
Saisissez l'URL de votre point de terminaison (doit être HTTPS)
Sélectionnez les événements que vous souhaitez recevoir
Enregistrez — vous recevrez un secret de signature

Événements Disponibles

Événement	Déclencheur
`visitor.blocked`	Un visiteur a été bloqué par une règle
`visitor.challenged`	Un visiteur a reçu un défi
`ban.created`	Un nouveau bannissement a été ajouté (manuel ou automatique)
`ban.expired`	Un bannissement a expiré ou a été levé
`anomaly.detected`	Le score de risque a dépassé le seuil
`rate_limit.exceeded`	Un visiteur a dépassé les limites de débit

Format de la Charge Utile

Toutes les charges utiles des webhooks suivent une structure cohérente :

{
  "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"
  }
}

Vérification de la Signature

Chaque requête webhook inclut un en-tête X-VF-Signature contenant une signature HMAC-SHA256. Vérifiez-la pour vous assurer que la charge utile provient de VisitorFilters :

$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;
}

Politique de Réessai

Si votre point de terminaison renvoie un code de statut non-2xx, nous réessayons la livraison :

1er réessai : 30 secondes
2ème réessai : 5 minutes
3ème réessai : 30 minutes
4ème réessai : 2 heures
5ème réessai : 24 heures

Après 5 tentatives échouées, la livraison est marquée comme échouée. Vous pouvez réessayer manuellement depuis le tableau de bord.

Bonnes Pratiques

Répondez rapidement avec 200 OK — traitez la charge utile de manière asynchrone si nécessaire.
Vérifiez toujours la signature avant de traiter.
Utilisez l'idempotence — les webhooks peuvent être livrés plus d'une fois.
Surveillez la santé de votre point de terminaison dans Webhooks → Livraisons.