Уебхукове

Уебхуковете позволяват на VisitorFilters да изпраща известия в реално време до вашия сървър при настъпване на конкретни събития. Това дава възможност за интеграция с вашата съществуваща инфраструктура, управление на инциденти или персонализирана автоматизация.

Настройване на уебхукове

Отидете в Сайтове → [Вашият сайт] → Уебхукове
Кликнете Добавяне на крайна точка
Въведете URL на вашата крайна точка (трябва да е HTTPS)
Изберете събитията, които искате да получавате
Запазете — ще получите тайния ключ за подписване

Налични събития

Събитие	Задействане
`visitor.blocked`	Посетител е блокиран от правило
`visitor.challenged`	На посетител е показано предизвикателство
`ban.created`	Добавена е нова забрана (ръчна или автоматична)
`ban.expired`	Забраната е изтекла или е вдигната
`anomaly.detected`	Рисковият резултат е превишил прага
`rate_limit.exceeded`	Посетителят е превишил лимитите за скорост

Формат на полезния товар

Всички полезни товари на уебхуковете следват последователна структура:

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

Верификация на подписа

Всяка уебхук заявка включва заглавка X-VF-Signature, съдържаща HMAC-SHA256 подпис. Верифицирайте го, за да се уверите, че полезният товар е изпратен от 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;
}

Политика за повторни опити

Ако крайната ви точка върне код на статус, различен от 2xx, ние повтаряме доставката:

1-ви повторен опит: 30 секунди
2-ри повторен опит: 5 минути
3-ти повторен опит: 30 минути
4-ти повторен опит: 2 часа
5-ти повторен опит: 24 часа

След 5 неуспешни опита доставката се маркира като неуспешна. Можете да повторите ръчно от таблото за управление.

Най-добри практики

Отговаряйте с 200 OK бързо — обработвайте полезния товар асинхронно, ако е необходимо.
Винаги верифицирайте подписа преди обработка.
Използвайте идемпотентност — уебхуковете може да се доставят повече от веднъж.
Наблюдавайте здравето на вашата крайна точка в Уебхукове → Доставки.