Webhooks¶

Bei einem Alert schickt Vesana einen JSON-POST an eine URL deiner Wahl. Damit lassen sich eigene Ticket-Systeme, n8n, Node-RED o. ä. anbinden. Für PagerDuty, Opsgenie, ntfy, Pushover, Telegram und die Chat-Dienste gibt es eigene Kanaltypen (siehe Notification Channels).

Konfiguration¶

Alerting → Kanäle → Neuer Kanal → Typ Webhook:

Feld	Wert
Name	z. B. „Ticket-Webhook" (Pflicht)
Tenant	nur beim Anlegen wählbar
Webhook URL	`http://` oder `https://` (Pflicht)

Mehr gibt es nicht: keine Methoden-Wahl (immer POST, Content-Type: application/json), keine eigenen Header, keine Payload-Vorlage, keine Signatur. Zur Absicherung des Empfängers ein geheimes Token in die URL schreiben (z. B. https://tickets.example.com/hook?token=…) und HTTPS verwenden; die URL wird verschlüsselt gespeichert und beim Bearbeiten maskiert angezeigt.

Ziele im internen Netz des Vesana-Servers (Loopback, Link-Local, Cloud-Metadaten, die Container des Stacks) werden abgewiesen; Adressen im eigenen LAN sind erlaubt.

Payload¶

{
  "type": "alert",
  "host_name": "web01.acme.local",
  "host_ip": "10.10.5.13",
  "service_name": "Disk /var",
  "status": "CRITICAL",
  "previous_status": "WARNING",
  "message": "Disk usage 96.4%",
  "triggered_at": "2026-10-19T10:15:30+00:00",
  "tenant_name": "Acme GmbH",
  "dashboard_url": "https://vesana.example.com/hosts/…",
  "duration_seconds": 320,
  "extra_data": { }
}

type: u. a. alert, recovery (Entwarnung) und test (Knopf Test senden).
duration_seconds und extra_data fehlen, wenn es nichts dazu gibt.
dashboard_url ist der Link auf den betroffenen Check bzw. das Gerät in Vesana; leer, wenn die Instanz ihre eigene Adresse nicht kennt (BASE_URL bzw. Agent-Server-URL).

Sammel-Meldungen¶

Ist in der Alert-Regel die Gruppierung aktiv, kommt ein POST pro Gruppe. Die Einzel-Einträge stehen dann in extra_data:

"extra_data": {
  "grouped": true,
  "alerts": [
    { "host": "web01", "service": "Disk /var", "status": "CRITICAL", "message": "…", "timestamp": "…" }
  ],
  "total_alert_count": 12,
  "overflow_count": 2,
  "hosts": ["web01"]
}

alerts enthält höchstens 10 Einträge, der Rest wird in overflow_count gezählt. Ein Empfänger sollte Einzel- und Sammel-Meldung unterscheiden (extra_data.grouped).

Zustellung und Wiederholung¶

Jede Antwort ab HTTP 400, ein Timeout (10 s) oder ein Verbindungsfehler gilt als Fehlschlag. Vesana wiederholt die Zustellung mit wachsendem Abstand (10 s, 30 s, 1 min, 2 min, 5 min, 10 min …, insgesamt bis zu 8 Versuche); danach gilt die Meldung als endgültig fehlgeschlagen und steht so im Zustell-Journal des Kanals. Der Empfänger kann eine Meldung daher mehr als einmal bekommen.

Test¶

Test senden in der Kanal-Zeile schickt eine Testmeldung ("type": "test", Host test-host, Status CRITICAL). Antwortet der Empfänger mit einem Fehler, steht der HTTP-Status mit dem Anfang der Antwort direkt am Kanal.