Webhook-Format

SilentShield kann Echtzeit-Benachrichtigungen per Webhook an Ihren Server senden. Konfigurieren Sie Webhook-URLs unter Dashboard → Benachrichtigungen.

Payload-Struktur

Alle Webhook-Payloads folgen dieser Struktur:

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

Event-Typen

Event	Description
`bot_detected`	Wird ausgelöst, wenn eine Anfrage als Bot klassifiziert wird.
`bot_spike`	Wird ausgelöst, wenn Bot-Erkennungen Ihren Alert-Schwellenwert innerhalb des konfigurierten Zeitfensters überschreiten.
`quota_warning`	Wird ausgelöst, wenn der Kontingentverbrauch 80% oder 90% erreicht.
`quota_exceeded`	Wird ausgelöst, wenn Ihr monatliches Kontingent überschritten wird.
`domain_verification_failed`	Wird ausgelöst, wenn eine Domain-Re-Verifizierungsprüfung fehlschlägt.
`key_rotated`	Wird ausgelöst, wenn ein API-Key rotiert wird.

Signatur-Verifizierung

Jeder Webhook enthält einen X-SilentShield-Signature Header mit einer HMAC-SHA256-Signatur. Verifizieren Sie diese Signatur, um die Authentizität des Webhooks sicherzustellen.

Den rohen Request-Body erhalten (als String, vor dem Parsen)
Den X-SilentShield-Signature Header-Wert auslesen
HMAC-SHA256 des Bodys mit Ihrem Webhook-Secret als Schlüssel berechnen
Die berechnete Signatur mit dem Header-Wert vergleichen

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

Wiederholungsrichtlinie

Wenn Ihr Endpunkt einen Nicht-2xx-Statuscode zurückgibt oder das Timeout überschreitet (10 Sekunden), wiederholt SilentShield die Zustellung bis zu 3 Mal mit exponentiellem Backoff (1 Minute, 5 Minuten, 30 Minuten). Nach 3 fehlgeschlagenen Versuchen wird der Webhook als fehlgeschlagen markiert und ist unter Dashboard → Benachrichtigungen → Fehlgeschlagene Zustellungen sichtbar.

Webhook-Secret

Ihr Webhook-Secret wird generiert, wenn Sie einen Webhook-Endpunkt im Dashboard erstellen. Sie können es unter Dashboard → Benachrichtigungen → Webhooks → Bearbeiten einsehen oder neu generieren.