Level-Webhooks senden Warn-, Geräte- und Gruppenereignisse an einen HTTP-Endpunkt, den Sie selbst verwalten. Verwenden Sie sie, wenn Ihre Integration ereignisgesteuerte Aktualisierungen benötigt, anstatt die öffentliche API abzufragen.

Dieser Artikel behandelt das Anforderungsformat und das Verhalten des Empfängers. Um einen Webhook zu erstellen, Ereignisse auszuwählen, das Secret zu verwalten und Zustellungsprotokolle in Level einzusehen, siehe Webhook-Einstellungen.

Informationen zu den Payload-Schemas für einzelne Ereignisse finden Sie in der Level-Entwicklerdokumentation.

ℹ️ HINWEIS: Dies sind ausgehende Ereignis-Webhooks. Um eine Level-Automatisierung aus einer eingehenden Anforderung zu starten, siehe Webhook-Auslöser.

Bevor Sie beginnen

Sie benötigen:

Administratorzugriff, um den Webhook in Level zu konfigurieren.
Einen öffentlich erreichbaren HTTPS-Endpunkt.
Ein hochentropisches Secret, das zwischen Level und Ihrem Empfänger geteilt wird.
Eine Möglichkeit, verarbeitete Ereignis-IDs zu speichern oder die Ereignisverarbeitung idempotent zu gestalten.

Konfigurieren Sie das Ziel und die Ereignisauswahl unter Einstellungen → Webhooks indem Sie folgen Webhook-Einstellungen.

Anforderungsformat

Level sendet ein HTTP POST mit:

Content-Type: application/json

Wenn der Webhook ein Secret hat, sendet Level außerdem:

X-Level-Signature: sha256=

Jedes Ereignis verwendet diesen JSON-Umschlag:

{  "event_type": "device_created",  "event_id": "550e8400-e29b-41d4-a716-446655440000",  "occurred_at": "2026-03-13T18:30:00.000Z",  "data": {    "id": "..."  }}

Feld	Typ	Beschreibung
`event_type`	Zeichenfolge	Gibt den Typ des Ereignisses an.
`event_id`	UUID	Identifiziert das Ereignis und bleibt gleich, wenn die Payload erneut zugestellt wird.
`occurred_at`	ISO 8601-Datum/Uhrzeit in UTC	Zeitpunkt, zu dem das Ereignis generiert wurde.
`data`	Objekt	Ressourcenspezifische Ereignisdaten.

Verwenden Sie die Webhook-Payload-Referenz für das Schema jedes data Objekt.

Ereignistypen

`event_type`	Wann es gesendet wird
`alert_active`	Eine neue Warnung wird ausgelöst.
`alert_resolved`	Eine vorhandene Warnung wird aufgelöst.
`device_created`	Ein Gerät wird hinzugefügt.
`device_updated`	Gerätedaten oder -konfiguration ändern sich.
`device_deleted`	Ein Gerät wird entfernt.
`group_created`	Eine Gerätegruppe wird erstellt.
`group_updated`	Der Name oder die Konfiguration einer Gruppe ändert sich.
`group_deleted`	Eine Gruppe wird gelöscht.

Welche Ereignistypen an einen Endpunkt geliefert werden, hängt von der in Einstellungen → Webhooks.

Signatur überprüfen

Wenn ein Secret konfiguriert ist, berechnet Level HMAC-SHA256 über den genauen JSON-Anforderungstext.

Überprüfen Sie die Anforderung, bevor Sie den Text parsen oder verarbeiten:

Lesen Sie den rohen Anforderungstext als Bytes.
Berechnen Sie HMAC-SHA256 über genau diese Bytes und verwenden Sie dabei das Webhook-Secret als Schlüssel.
Kodieren Sie den Digest als kleingeschriebenes Hexadezimal.
Stellen Sie dem Digest sha256=.
Vergleichen Sie ihn mit X-Level-Signature mit einem Vergleich in konstanter Zeit.
Lehnen Sie die Anforderung ab, wenn die Werte nicht übereinstimmen.

⚠️ WARNUNG: Das Parsen und erneute Serialisieren des JSON vor der HMAC-Berechnung kann Leerzeichen oder Feldformatierungen ändern und einen anderen Digest erzeugen. Überprüfen Sie den rohen Anforderungstext.

Der Signatur-Header wird weggelassen, wenn der Webhook kein Secret hat. Konfigurieren Sie ein Secret für Produktionsziele.

Ereignisse sicher verarbeiten

Ein Empfänger sollte:

Anforderungen nur über HTTPS akzeptieren.
Überprüfen Sie X-Level-Signature bevor Sie der Payload vertrauen.
Validieren Sie event_type, event_id, occurred_at, und das erwartete data Schema.
Speichern Sie event_id oder verwenden Sie eine idempotente Operation.
Umfangreichere Aufgaben in Ihre eigene Warteschlange einreihen.
Geben Sie eine erfolgreiche 2xx Antwort nach Annahme des Ereignisses.

Fehlgeschlagene Anforderungen können automatisch wiederholt werden, und ein Administrator kann eine Zustellung in Level manuell erneut ausführen. Beide Wege können dieselbe event_id mehr als einmal.

💡 TIPP: Verwenden Sie event_id als Idempotenzschlüssel. Wenn Ihr Empfänger sie bereits verarbeitet hat, geben Sie Erfolg zurück, ohne den Vorgang zu wiederholen.

Zustellung beheben

Verwenden Sie Einstellungen → Webhooks → Anforderungen um aufgezeichnete Versuche einzusehen. Die Anforderungsdetails können Folgendes enthalten:

Zustellungsstatus.
HTTP-Antwortstatus.
Ziel-URL.
Ereigniszeitpunkt.
Verbindungs- oder HTTP-Fehler.
Antworttext.

Verwenden Sie nach der Behebung des Ziels Anforderung erneut ausführen um die gespeicherte Payload erneut zu senden. Eine erneute Ausführung verwendet dieselbe Ereignis-ID, daher muss der Empfänger sie als mögliches Duplikat behandeln.

Siehe Webhook-Einstellungen für den vollständigen Konfigurations- und Zustellungsprotokoll-Workflow.

Verwandte Artikel

Webhooks: Entwicklerhandbuch