Level-Webhooks senden Alarm-, Geräte- und Gruppenereignisse an einen HTTP-Endpunkt Ihrer Wahl. Verwenden Sie diese, wenn Ihre Integration ereignisgesteuerte Aktualisierungen benötigt, anstatt die öffentliche API abzufragen.

Dieser Artikel beschreibt das Anforderungsformat und das Verhalten des Empfängers. Informationen zum Erstellen eines Webhooks, zur Auswahl von Ereignissen, zur Verwaltung des Geheimnisses und zur Überprüfung von Übermittlungsprotokollen in Level finden Sie unter Webhook-Einstellungen.

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

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

Bevor Sie beginnen

Sie benötigen:

Administratorzugriff zum Konfigurieren des Webhooks in Level.
Einen öffentlich erreichbaren HTTPS-Endpunkt.
Ein hochentropisches Geheimnis, 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 durch Befolgen von Webhook-Einstellungen.

Anforderungsformat

Level sendet einen HTTP-POST mit:

Content-Type: application/json

Wenn der Webhook ein Geheimnis besitzt, sendet Level zusätzlich:

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`	Zeichenkette	Gibt den Typ des Ereignisses an.
`event_id`	UUID	Identifiziert das Ereignis und bleibt gleich, wenn der 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`	Zeitpunkt der Übermittlung
`alert_active`	Ein neuer Alarm wird ausgelöst.
`alert_resolved`	Ein bestehender Alarm wird aufgelöst.
`device_created`	Ein Gerät wird hinzugefügt.
`device_updated`	Gerätedaten oder -konfiguration werden geändert.
`device_deleted`	Ein Gerät wird entfernt.
`group_created`	Eine Gerätegruppe wird erstellt.
`group_updated`	Der Name oder die Konfiguration einer Gruppe wird geändert.
`group_deleted`	Eine Gruppe wird gelöscht.

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

Signatur überprüfen

Wenn ein Geheimnis konfiguriert ist, berechnet Level HMAC-SHA256 über den exakten 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 diese exakten Bytes und verwenden Sie dabei das Webhook-Geheimnis als Schlüssel.
Kodieren Sie den Digest als kleingeschriebenes Hexadezimal.
Stellen Sie dem Digest sha256=.
Vergleichen Sie ihn mit X-Level-Signature mithilfe eines Vergleichs mit konstanter Zeit.
Lehnen Sie die Anforderung ab, wenn die Werte nicht übereinstimmen.

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

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

Ereignisse sicher verarbeiten

Ein Empfänger sollte:

Anforderungen nur über HTTPS annehmen.
Überprüfen Sie X-Level-Signature bevor er dem Payload vertraut.
Validieren Sie event_type, event_id, occurred_at, und das erwartete data Schema.
Erfassen Sie event_id oder verwenden Sie eine idempotente Operation.
Längere Aufgaben in eine eigene Warteschlange einreihen.
Eine erfolgreiche 2xx Antwort nach dem Annehmen des Ereignisses zurückgeben.

Fehlgeschlagene Anforderungen können automatisch wiederholt werden, und ein Administrator kann eine Übermittlung in Level manuell erneut ausführen. In beiden Fällen kann dieselbe event_id mehr als einmal.

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

Übermittlung zur Fehlerbehebung

Verwenden Sie Einstellungen → Webhooks → Anforderungen , um aufgezeichnete Versuche zu überprüfen. Die Anforderungsdetails können Folgendes enthalten:

Übermittlungsstatus.
HTTP-Antwortstatus.
Ziel-URL.
Ereigniszeitpunkt.
Verbindungs- oder HTTP-Fehler.
Antworttext.

Nachdem Sie das Ziel korrigiert haben, verwenden Sie Anforderung erneut ausführen , um den gespeicherten Payload erneut zu senden. Eine erneute Ausführung verwendet dieselbe Ereignis-ID, daher muss der Empfänger diese als mögliches Duplikat behandeln.

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

Verwandte Artikel

Webhooks: Entwicklerhandbuch