Format webhooków

SilentShield może wysyłać powiadomienia w czasie rzeczywistym na Twój serwer za pomocą webhooków. Skonfiguruj adresy URL webhooków w Panel → Powiadomienia.

Struktura danych

Wszystkie dane webhooków mają następującą strukturę:

{"event": "bot_detected", "timestamp": "2025-01-15T10:30:00Z", "data": {"keyId": "key_abc", "domain": "example.com", "ip": "203.0.113.42", "verdict": "bot", "score": 0.15, "userAgent": "Mozilla/5.0...", "page": "/contact"}}

Typy zdarzeń

Event	Description
`bot_detected`	Wyzwalane, gdy żądanie zostanie sklasyfikowane jako bot.
`bot_spike`	Wyzwalane, gdy wykrycia botów przekroczą próg alertu w skonfigurowanym oknie czasowym.
`quota_warning`	Wyzwalane, gdy wykorzystanie limitu osiągnie 80% lub 90%.
`quota_exceeded`	Wyzwalane, gdy miesięczny limit zostanie przekroczony.
`domain_verification_failed`	Wyzwalane, gdy ponowna weryfikacja domeny nie powiedzie się.
`key_rotated`	Wyzwalane, gdy klucz API zostanie zrotowany.

Weryfikacja podpisu

Każdy webhook zawiera nagłówek X-SilentShield-Signature z podpisem HMAC-SHA256. Zweryfikuj ten podpis, aby upewnić się, że webhook jest autentyczny.

Pobierz surową treść żądania (jako ciąg znaków, przed parsowaniem)
Pobierz wartość nagłówka X-SilentShield-Signature
Oblicz HMAC-SHA256 treści, używając sekretu webhooka jako klucza
Porównaj obliczony podpis z wartością nagłówka

const crypto = require('crypto');

function verifyWebhook(body, signature, secret) {
  const computed = crypto
    .createHmac('sha256', secret)
    .update(body)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(computed),
    Buffer.from(signature)
  );
}

Polityka ponownych prób

Jeśli Twój punkt końcowy zwróci kod statusu inny niż 2xx lub upłynie limit czasu (10 sekund), SilentShield ponawia dostarczenie do 3 razy z wykładniczym opóźnieniem (1 minuta, 5 minut, 30 minut). Po 3 nieudanych próbach webhook jest oznaczany jako nieudany i widoczny w Panel → Powiadomienia → Nieudane dostarczenia.

Sekret webhooka

Twój sekret webhooka jest generowany podczas tworzenia punktu końcowego webhooka w panelu. Możesz go wyświetlić lub wygenerować ponownie w Panel → Powiadomienia → Webhooki → Edytuj.