Formato dei webhook

SilentShield può inviare notifiche in tempo reale al tuo server tramite webhook. Configura gli URL dei webhook in Pannello → Notifiche.

Struttura del payload

Tutti i payload dei webhook seguono questa struttura:

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

Tipi di evento

Event	Description
`bot_detected`	Attivato quando una richiesta viene classificata come bot.
`bot_spike`	Attivato quando i rilevamenti di bot superano la soglia di avviso nella finestra configurata.
`quota_warning`	Attivato quando l'utilizzo della quota raggiunge l'80% o il 90%.
`quota_exceeded`	Attivato quando la quota mensile viene superata.
`domain_verification_failed`	Attivato quando una ri-verifica del dominio fallisce.
`key_rotated`	Attivato quando una API key viene ruotata.

Verifica della firma

Ogni webhook include un'intestazione X-SilentShield-Signature contenente una firma HMAC-SHA256. Verifica questa firma per assicurarti che il webhook sia autentico.

Ottieni il corpo grezzo della richiesta (come stringa, prima dell'analisi)
Ottieni il valore dell'intestazione X-SilentShield-Signature
Calcola l'HMAC-SHA256 del corpo usando il tuo segreto webhook come chiave
Confronta la firma calcolata con il valore dell'intestazione

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

Politica di ripetizione

Se il tuo endpoint restituisce un codice di stato non-2xx o scade il timeout (10 secondi), SilentShield riprova la consegna fino a 3 volte con backoff esponenziale (1 minuto, 5 minuti, 30 minuti). Dopo 3 tentativi falliti, il webhook viene contrassegnato come fallito ed è visibile in Pannello → Notifiche → Consegne fallite.

Segreto del webhook

Il segreto del webhook viene generato quando crei un endpoint webhook nel pannello. Puoi visualizzarlo o rigenerarlo in Pannello → Notifiche → Webhook → Modifica.