Einführung

Webhooks senden ausgehende Level-Ereignisse an Ihre eigenen Systeme. Wenn ein ausgewähltes Alarm-, Geräte- oder Gruppenereignis eintritt, stellt Level eine HTTP-POST-Anfrage an die von Ihnen konfigurierte URL in die Warteschlange.

Dieser Artikel behandelt ausgehende Ereignis-Webhooks, die unter Einstellungen → Webhooks. Um eine Level-Automatisierung aus einer eingehenden Anfrage zu starten, siehe Webhook-Auslöser.

Informationen zu Anfrageformaten, Signaturverifizierung und Empfängerhinweisen finden Sie unter Webhooks: Entwicklerhandbuch.

⚙️ VORAUSSETZUNGEN

Ein öffentlich erreichbarer Endpunkt, der HTTP-POST-Anfragen mit einem JSON-Body akzeptiert.
Administratorzugang zu Ihrer Level-Organisation.
Ein sicheres Geheimnis zur Signaturverifizierung.

Verwenden Sie einen HTTPS-Endpunkt, damit Webhook-Inhalte und Signaturen während der Übertragung verschlüsselt sind.

Webhook-Einstellungen

Gehen Sie zu Einstellungen → Webhooks. Die Seite hat zwei Registerkarten:

Webhooks listet Ihre konfigurierten Ziele auf.
Anfragen zeigt Zustellversuche und Antworten.

Einen Webhook erstellen

Klicken Sie auf + Webhook hinzufügen oder + Webhook erstellen im leeren Zustand.
Geben Sie die Ziel- URL.
Geben Sie ein Geheimnis zum Signieren von Anfragen ein.
Lassen Sie Aktiviert ein, um die Zustellung zu starten, oder deaktivieren Sie es, um den Webhook im pausierten Zustand zu speichern.
Unter Zu sendende Ereignisseeingeschaltet, wählen Sie alle derzeit verfügbaren Ereignistypen oder wählen Sie einzelne Typen aus.
Klicken Sie auf Webhook hinzufügen.

💡 TIPP: Generieren Sie ein hochentropisches Geheimnis mit einem Passwort-Manager und speichern Sie es im Secret-Manager Ihres empfangenden Dienstes.

⚠️ WARNUNG: Das gespeicherte Geheimnis kann später nicht mehr eingesehen werden. Speichern Sie es, bevor Sie auf Webhook hinzufügen. Falls es verloren geht oder bekannt wird, bearbeiten Sie den Webhook, legen Sie ein neues Geheimnis fest und aktualisieren Sie Ihren empfangenden Dienst.

Verfügbare Ereignistypen

Ereignis	`event_type`	Wann es gesendet wird
Alarm aktiv	`alert_active`	Ein neuer Alarm wird ausgelöst.
Alarm behoben	`alert_resolved`	Ein bestehender Alarm wird behoben.
Gerät erstellt	`device_created`	Ein Gerät wird hinzugefügt.
Gerät aktualisiert	`device_updated`	Gerätedaten oder Konfiguration werden geändert.
Gerät gelöscht	`device_deleted`	Ein Gerät wird entfernt.
Gruppe erstellt	`group_created`	Eine Gerätegruppe wird erstellt.
Gruppe aktualisiert	`group_updated`	Der Name oder die Konfiguration einer Gruppe wird geändert.
Gruppe gelöscht	`group_deleted`	Eine Gruppe wird gelöscht.

Durch die Auswahl aller Ereignisse werden alle derzeit in Level angezeigten Ereignistypen gespeichert. Überprüfen Sie den Webhook nach der Veröffentlichung neuer Ereignistypen, wenn Sie diese abonnieren möchten.

Nutzlaststruktur

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	Einer der konfigurierten Ereignistypen.
`event_id`	UUID	Identifiziert das Ereignis und bleibt stabil, wenn dieselbe Nutzlast erneut zugestellt wird.
`occurred_at`	ISO 8601 Datum/Uhrzeit in UTC	Zeitpunkt, zu dem das Ereignis generiert wurde.
`data`	Objekt	Ressourcenspezifische Ereignisdaten.

Verwenden Sie event_id als Idempotenzschlüssel. Eine Anfrage kann aufgrund automatischen Wiederholungsverhaltens oder eines manuellen erneuten Ausführens wiederholt werden.

Siehe Webhooks: Entwicklerhandbuch für das Anfrageformat, die Signaturverifizierung und die Empfänger-Checkliste.

Anfrage-Signaturen verifizieren

Wenn ein Geheimnis konfiguriert ist, berechnet Level HMAC-SHA256 über den genauen JSON-Anfrage-Body und sendet das Ergebnis in diesem Header:

X-Level-Signature: sha256=

Verifizieren Sie die Signatur, bevor Sie den JSON parsen oder verarbeiten:

Lesen Sie den rohen Anfrage-Body als Bytes.
Berechnen Sie HMAC-SHA256 über genau diese Bytes, wobei das Webhook-Geheimnis als Schlüssel verwendet wird.
Kodieren Sie den Digest als Kleinbuchstaben-Hexadezimalzahl und stellen Sie ihm sha256=.
Vergleichen Sie den berechneten Wert mit X-Level-Signature mithilfe eines Zeitkonstanten-Vergleichs.
Lehnen Sie die Anfrage ab, wenn die Werte nicht übereinstimmen.

ℹ️ HINWEIS: Der Signatur-Header wird weggelassen, wenn der Webhook kein Geheimnis hat. Konfigurieren Sie ein Geheimnis für jeden produktiven Webhook.

Geben Sie eine erfolgreiche 2xx Antwort zurück, nachdem das Ereignis akzeptiert wurde. Wenn die Verarbeitung Zeit in Anspruch nehmen kann, legen Sie das verifizierte Ereignis in Ihre eigene Warteschlange und kehren Sie zurück, bevor Sie die zeitintensive Arbeit durchführen.

Zustellprotokolle überprüfen

Öffnen Sie die Anfragen Registerkarte, um aufgezeichnete Zustellversuche zu überprüfen.

Jede Zeile enthält:

Zustellstatus.
HTTP-Antwortstatus, sofern das Ziel einen zurückgegeben hat.
Ziel-URL.

Öffnen Sie eine Zeile, um Details wie Ereigniszeit, vollständige URL, Fehlermeldung und Antwort-Body zu sehen.

Automatische Wiederholungen

Fehlgeschlagene Zustellungen können automatisch wiederholt werden. Ihr Endpunkt kann dasselbe event_id mehr als einmal, auch wenn eine frühere Anfrage erfolgreich verarbeitet wurde, aber ihre Antwort Level nicht erreicht hat.

Speichern Sie verarbeitete Ereignis-IDs oder machen Sie jeden Vorgang von Natur aus idempotent.

Eine Anfrage manuell erneut ausführen

Nach der Korrektur des Ziels oder Empfängers öffnen Sie eine Anfrage und klicken Sie auf Anfrage erneut ausführen. Level sendet die ursprünglich gespeicherte Nutzlast sofort erneut.

⚠️ WARNUNG: Durch erneutes Ausführen einer Anfrage wird dasselbe Ereignis erneut gesendet. Deduplizieren Sie über event_id vor dem Erstellen von Datensätzen oder der Durchführung anderer nicht-idempotenter Vorgänge.

Vorhandene Webhooks verwalten

Die Webhooks Registerkarte zeigt jede Ziel-URL und den Aktivierungsstatus. Von dort aus können Sie die URL, das Geheimnis, die Ereignisauswahl oder den Aktivierungsstatus bearbeiten oder den Webhook löschen.

Das Ausschalten von Aktiviert aus pausiert zukünftige Zustellungen, ohne die Konfiguration zu löschen. Schalten Sie es wieder ein, wenn das Ziel bereit ist.

Häufig gestellte Fragen

Wer kann Webhooks verwalten? Organisationsadministratoren können Webhooks erstellen, bearbeiten, anzeigen, erneut ausführen und löschen.
In welchem Format sendet Level? Level sendet einen HTTP-POST mit Content-Type: application/json und den oben dokumentierten Umschlag.
Wie verifiziere ich eine Anfrage? Konfigurieren Sie ein Geheimnis und verifizieren Sie den X-Level-Signature HMAC gegen den rohen Body vor dem Parsen von JSON.
Warum habe ich dasselbe Ereignis zweimal erhalten? Eine fehlgeschlagene Antwort, automatische Wiederholung oder manuelles erneutes Ausführen kann eine Zustellung wiederholen. Deduplizieren Sie mit event_id.
Warum ist eine Anfrage als fehlgeschlagen markiert? Öffnen Sie es unter Anfragen und überprüfen Sie den Statuscode, den Fehler und den Antwort-Body. Stellen Sie sicher, dass die URL öffentlich erreichbar ist und eine erfolgreiche 2xx Antwort.
Kann ich Ereignisse an mehr als einen Endpunkt senden? Ja. Erstellen Sie einen Webhook für jedes Ziel und wählen Sie die Ereignistypen separat aus.
Kann ich ein verlorenes Geheimnis wiederherstellen? Nein. Legen Sie ein neues Geheimnis für den Webhook fest und aktualisieren Sie den empfangenden Dienst.

Verwandte Artikel