Webhooks: Sicherheit und Zustellung

Übersicht

Superheld liefert Detection Events in Echtzeit per Webhook an externe Systeme. Diese Seite dokumentiert die Sicherheitsmechanismen, Zustellsemantik und Empfehlungen für idempotente Consumer.

Aktueller Workspace-Hinweis: Die Runtime akzeptiert ausschließlich https://-Webhook-Ziele. Loopback-, Link-Local- und private Zieladressen sowie Redirects dorthin werden abgelehnt. Bereits bei der Registrierung wird der Host auf auflösbare öffentliche Zieladressen geprüft.

Zustellsemantik

At-least-once Delivery — Webhooks werden mindestens einmal zugestellt. Consumer müssen mit Duplikaten umgehen können.
Keine Reihenfolgegarantie — Events können in abweichender Reihenfolge eintreffen. Consumer sollten timestamp zur Sortierung verwenden.

Signaturverifizierung

Jeder Webhook-Request enthält einen HMAC-SHA256-Signatur-Header, mit dem Consumer die Authentizität und Integrität des Payloads prüfen können.

Parameter	Wert
Header	`X-Superheld-Signature`
Algorithmus	HMAC-SHA256
Signing Input	Der vollständige Request Body (UTF-8-kodiert)
Signing Secret	Wird bei der Webhook-Konfiguration generiert

Beispiel (bash):

echo -n "$PAYLOAD" | openssl dgst -sha256 -hmac "$SIGNING_SECRET"

Replay-Schutz

Superheld sendet einen X-Superheld-Timestamp-Header mit dem Unix-Zeitstempel der Webhook-Auslieferung. Verwenden Sie diesen Header (nicht das Payload-Feld) für die Replay-Prüfung.

Empfohlene Implementierung (Consumer-seitig):

Prüfen Sie den X-Superheld-Timestamp-Header gegen die aktuelle Serverzeit.
Lehnen Sie Events ab, die älter als 5 Minuten sind (konfigurierbar).
Speichern Sie verarbeitete event_id-Werte für mindestens 24 Stunden zur Deduplizierung.

Idempotenz

Jedes Event enthält eine eindeutige event_id.
Consumer sollten event_id als Idempotenz-Schlüssel verwenden.
Empfohlener Ablauf: Vor Verarbeitung prüfen ob event_id bereits verarbeitet wurde.

Superheld sendet zusätzlich einen X-Superheld-Idempotency-Key-Header. Verwenden Sie diesen Header in Kombination mit der event_id im Payload zur Deduplizierung.

Aktueller Workspace-Hinweis: Webhook-Zustellung wird derzeit aus akzeptierten warn-/block-Pfaden ausgelöst. allow-Events bleiben im Event-Feed, erzeugen aber keine Webhook-Zustellung.

Retry-Verhalten und Dead Letter Queue

Versuch	Wartezeit
1	sofortiger Erstversuch
2	1 s
3	2 s

Retry nur bei 429, 5xx und Verbindungsfehlern.
Bei nicht-retrybaren 4xx-Antworten wird der Delivery-Versuch sofort beendet.
Nach insgesamt 3 Versuchen: Event wird in die Dead-Letter-Queue verschoben.

Die aktuelle Workspace-Runtime enthält DLQ-Retention für 7 Tage. Es gibt weiterhin kein Dashboard zum manuellen Replay, aber es existiert jetzt eine Runtime-API fuer DLQ-Listing und Replay ueber GET /webhooks/dlq und POST /webhooks/dlq.

Payload-Format

Jeder Webhook-Request enthält ein JSON-Objekt mit dem kanonischen Event-Schema:

{
  "event_id": "evt_7f2a9c",
  "type": "risk.event.created",
  "timestamp": "2026-03-14T14:32:08Z",
  "tenant_id": "tenant-acme",
  "device_id": "dev_3c8a1f",
  "threat_category": "phishing",
  "confidence": 0.94,
  "action_taken": "block",
  "policy_id": "pol_default",
  "severity": "high",
  "description": "Gefälschte Login-Seite erkannt und blockiert.",
  "indicators": ["sha256:a1b2c3d4e5f6..."],
  "metadata": {
    "agent_version": "0.1.0",
    "model_version": "detect-v3.2",
    "device_platform": "android"
  }
}

Kanonische threat_category-Werte: phone_scam, social_engineering, malicious_app, phishing, remote_control, deepfake.

Webhook-Ablauf

Konfiguration

Dashboard: Einstellungen → Integrationen → SIEM → Webhook
HTTPS-Endpunkt erforderlich
Interne, private oder loopback-nahe Zieladressen sind in der aktuellen Workspace-Runtime nicht erlaubt
DNS-Auflösungen auf private oder loopback-nahe Zieladressen werden bereits bei Registrierung abgelehnt
Aktuelle Workspace-Runtime erwartet tenant_id, url und secret, sofern der Tenant nicht bereits ueber den Secure Mux gebunden ist
Zustellung erfolgt in der aktuellen Workspace-Runtime asynchron mit begrenzter Parallelitaet, damit langsame Empfaenger den Event-Ingest nicht direkt blockieren
Schweregrad-Filter: low, medium, high, critical
Create-/List-Responses redigieren secret und enthalten Delivery-Metadaten wie last_delivery_status, last_delivery_error, last_delivery_at und last_delivery_attempts
Persistierte Webhook-Secrets erfordern in der aktuellen Workspace-Runtime SUPERHELD_SECRET_KEY_B64; ohne diesen Schlüssel fällt der persistente Webhook-Store auf In-Memory zurück statt Secrets im Klartext zu speichern
DLQ-Eintraege lassen sich ueber GET /webhooks/dlq abrufen; POST /webhooks/dlq replayt gezielt einen entry_id-Eintrag oder kompatibel dazu den neuesten Eintrag eines Webhooks; DELETE /webhooks/dlq?entry_id=... quittiert bzw. loescht einen Eintrag

Weiterführende Seiten

SIEM-Integration — Vollständiger SIEM-Workflow
Telemetrie & Logging — Event-Schema und Aufbewahrung
API-Übersicht — REST-API als Alternative zu Webhooks
OpenAPI-Spezifikation