Webhooks

Los webhooks permiten que VisitorFilters envíe notificaciones en tiempo real a su servidor cuando ocurren eventos específicos. Esto permite la integración con su infraestructura existente, gestión de incidentes o automatización personalizada.

Configurar Webhooks

Vaya a Sitios → [Su Sitio] → Webhooks
Haga clic en Agregar Endpoint
Ingrese la URL de su endpoint (debe ser HTTPS)
Seleccione los eventos que desea recibir
Guarde — recibirá un secreto de firma

Eventos Disponibles

Evento	Disparador
`visitor.blocked`	Un visitante fue bloqueado por una regla
`visitor.challenged`	A un visitante se le mostró un desafío
`ban.created`	Se agregó una nueva prohibición (manual o automática)
`ban.expired`	Una prohibición expiró o fue levantada
`anomaly.detected`	La puntuación de riesgo superó el umbral
`rate_limit.exceeded`	Un visitante superó los límites de velocidad

Formato del Payload

Todos los payloads de webhook siguen una estructura consistente:

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

Verificación de Firma

Cada solicitud de webhook incluye una cabecera X-VF-Signature que contiene una firma HMAC-SHA256. Verifíquela para asegurarse de que el payload proviene 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;
}

Política de Reintentos

Si su endpoint devuelve un código de estado no 2xx, reintentamos la entrega:

1er reintento: 30 segundos
2do reintento: 5 minutos
3er reintento: 30 minutos
4to reintento: 2 horas
5to reintento: 24 horas

Después de 5 intentos fallidos, la entrega se marca como fallida. Puede reintentar manualmente desde el panel de control.

Buenas Prácticas

Responda con 200 OK rápidamente — procese el payload de forma asíncrona si es necesario.
Siempre verifique la firma antes de procesar.
Use idempotencia — los webhooks pueden entregarse más de una vez.
Monitoree el estado de su endpoint en Webhooks → Entregas.