Einführung

Konfigurieren Sie HTTP-Callbacks, um Level-Ereignisse in Echtzeit an Ihre eigenen Systeme zu übermitteln. Wenn in Level etwas passiert – ein neuer Alert ausgelöst wird, ein Gerät hinzugefügt wird, eine Gruppe aktualisiert wird – sendet Level eine POST-Anfrage an die von Ihnen angegebene URL, sodass Sie in Ihren eigenen Tools darauf reagieren können, ohne die API abfragen zu müssen.

Die vollständige API-Referenz und Payload-Schemata für einzelne Ereignisse finden Sie in der Level Developer Documentation.

⚙️ VORAUSSETZUNGEN

Ein öffentlich zugänglicher HTTPS-Endpunkt, der bereit ist, POST-Anfragen mit einem JSON-Body zu empfangen.
Administratorzugriff auf Ihre Level-Organisation.

Webhook-Einstellungen

Navigieren Sie zu Einstellungen → Webhooks. Die Seite hat zwei Tabs:

Webhooks — Ihre konfigurierten Webhooks
Anfragen — das Zustellungsprotokoll für alle ausgehenden Anfragen

Einen Webhook erstellen

1. Klicken Sie auf + Webhook hinzufügen (oben rechts) oder + Webhook erstellen (leerer Zustand).

2. Geben Sie die Ziel- URL. Hierhin wird Level die Ereignisdaten per POST übermitteln. Verwenden Sie HTTPS.

3. (Optional) Geben Sie ein Secretein. Level verwendet dies, um jede ausgehende Anfrage zu signieren, damit Ihr Endpunkt überprüfen kann, dass der Payload von Level stammt.

💡 TIPP: Generieren Sie Ihr Secret mit einem Passwort-Manager oder openssl rand -hex 32ein. Verwenden Sie eine hochentropische zufällige Zeichenkette.

⚠️ WARNUNG: Das Secret kann nach dem Speichern nicht mehr eingesehen werden. Kopieren Sie es, bevor Sie auf Webhook hinzufügen — Sie benötigen es in Ihrem Endpunkt-Code zur Überprüfung von Signaturen.

4.. Der Aktiviert ist standardmäßig aktiviert. Lassen Sie es aktiviert, um sofort Ereignisse zu empfangen. Deaktivieren Sie es, um die Zustellung zu pausieren, ohne den Webhook zu löschen.

5. Unter Zu sendende Ereignisse, wählen Sie aus, was diesen Webhook auslöst:

Alle Ereignistypen senden — Level sendet jeden Ereignistyp, einschließlich aller zukünftig hinzugefügten.
Typen zum Senden auswählen — wählen Sie aus der folgenden Liste aus.

Verfügbare Ereignistypen

Ereignis	Wann es ausgelöst wird
Alert aktiv	Ein neuer Alert wird auf einem Gerät ausgelöst
Alert gelöst	Ein vorhandener Alert wird gelöst
Gerät erstellt	Ein neues Gerät wird Ihrem Konto hinzugefügt
Gerät gelöscht	Ein Gerät wird aus Ihrem Konto entfernt
Gerät aktualisiert	Die Daten oder Konfiguration eines vorhandenen Geräts werden geändert
Gruppe erstellt	Eine neue Gerätegruppe wird erstellt
Gruppe gelöscht	Eine Gerätegruppe wird dauerhaft gelöscht
Gruppe aktualisiert	Name oder Konfiguration einer Gruppe wird geändert

ℹ️ HINWEIS: Wenn Sie Typen zum Senden auswählen, werden zukünftig in Level hinzugefügte Ereignistypen nicht automatisch einbezogen. Wechseln Sie zu Alle Ereignistypen senden wenn Sie eine vorwärtskompatible Zustellung wünschen.

6. Klicken Sie auf Webhook hinzufügen zum Speichern.

Payload-Struktur

Jede Webhook-Zustellung – unabhängig vom Ereignistyp – verwendet denselben JSON-Umschlag:

{
  "event_type": "device_created",
  "event_id": "a3f1b2c4-...",
  "occurred_at": "2026-03-13T18:30:00Z",
  "data": { ... }
}

Feld	Typ	Beschreibung
`event_type`	string	Einer der 8 oben aufgeführten Ereignistypen
`event_id`	UUID	Eindeutig pro Ereignis; stabil über Wiederholungen hinweg — verwenden Sie dies zur Deduplizierung
`occurred_at`	ISO 8601 Datum/Uhrzeit (UTC)	Zeitpunkt, zu dem das Ereignis generiert wurde
`data`	object	Ressourcenspezifischer Payload für dieses Ereignis

💡 TIPP: Verwenden Sie event_id um Ihren Endpunkt idempotent zu gestalten. Level wiederholt fehlgeschlagene Zustellungen automatisch, sodass dasselbe Ereignis mehr als einmal eintreffen kann.

ℹ️ HINWEIS: Für vollständige ereignisspezifische data Schemata finden Sie in der Level Developer Documentation.

Anfrage-Signaturen überprüfen

Wenn Sie ein Secret konfiguriert haben, fügt Level einen X-Level-Signature Header bei jeder Anfrage. Das Format ist sha256=<hex_digest>.

So überprüfen Sie:

Nehmen Sie den rohen JSON-Anfrage-Body als Zeichenkette.
Berechnen Sie HMAC-SHA256 dieser Zeichenkette, wobei Ihr Secret als Schlüssel verwendet wird.
Stellen Sie dem Ergebnis sha256= und vergleichen Sie ihn mit dem X-Level-Signature Header-Wert.
Wenn sie übereinstimmen, stammt die Anfrage von Level.

ℹ️ HINWEIS: Der X-Level-Signature Header ist nur vorhanden, wenn ein Secret für den Webhook konfiguriert wurde. Wenn Sie keines gesetzt haben, sollten Sie den Webhook bearbeiten, um eines hinzuzufügen.

Zustellungsprotokolle überprüfen

Der Anfragen Tab zeigt jede ausgehende Anfrage, die Level über alle konfigurierten Webhooks hinweg versucht hat.

Jede Zeile zeigt:

Status — Badge für Erfolg oder Fehlschlag
Statuscode — der HTTP-Antwort-Code von Ihrem Endpunkt (oder -- wenn die Verbindung vor einer Antwort fehlschlug)
URL — das Ziel für diese Anfrage

Klicken Sie auf eine beliebige Zeile, um das Detailfeld zu öffnen.

Das Detailfeld zeigt:

Ereigniszeit — wann das Ereignis aufgetreten ist
Statuscode — HTTP-Antwort von Ihrem Server
Vollständige URL — die genaue URL, an die Level gesendet hat
Fehlermeldung — der Verbindungs- oder HTTP-Fehler, falls vorhanden
Antwort-Body — was Ihr Endpunkt zurückgegeben hat (oder die rohe Fehlerausgabe)

Automatische Wiederholungsversuche

Wenn eine Zustellung fehlschlägt, wiederholt Level den Versuch automatisch – insgesamt bis zu 3 Versuche. Jeder Wiederholungsversuch wartet ungefähr 2 Minuten plus eine zufällige Verzögerung von 1–60 Sekunden. Nach 3 fehlgeschlagenen Versuchen hört Level auf zu versuchen und protokolliert den endgültigen Fehlschlag. Es wird kein Alert ausgelöst und der Webhook wird nicht deaktiviert.

ℹ️ HINWEIS: Da Level automatisch wiederholt, kann dasselbe Ereignis mehr als einmal zugestellt werden. Verwenden Sie event_id zur Deduplizierung auf Ihrer Seite.

Eine fehlgeschlagene Anfrage manuell erneut ausführen

Wenn Sie das zugrunde liegende Problem behoben haben und nicht auf den nächsten Wiederholungsversuch warten möchten, klicken Sie auf Anfrage erneut ausführen am unteren Rand des Detailfelds. Level sendet den ursprünglichen Payload sofort erneut.

⚠️ WARNUNG: Anfrage erneut ausführen sendet denselben Payload erneut. Wenn Ihr Endpunkt nicht idempotent ist, kann dies zu Duplikaten führen. Überprüfen Sie event_id vor der Verarbeitung.

Vorhandene Webhooks verwalten

Im Webhooks Tab wird jeder konfigurierte Webhook mit seiner URL und seinem Aktivierungsstatus aufgelistet. Von dort aus können Sie die Konfiguration bearbeiten, ihn aktivieren oder deaktivieren oder löschen.

ℹ️ HINWEIS: Das Deaktivieren eines Webhooks stoppt die Zustellung, ohne ihn oder seinen Anfrageverlauf zu löschen. Verwenden Sie dies, wenn Ihr Endpunkt sich im Wartungsmodus befindet.

FAQ

Welches Format verwendet Level für Webhook-Payloads? Level sendet einen HTTP-POST mit einem JSON-Body. Jedes Ereignis verwendet denselben Umschlag: event_type, event_id, occurred_at, und data. Das data Objekt enthält den ressourcenspezifischen Payload für diesen Ereignistyp. Siehe die Level Developer Documentation für vollständige ereignisspezifische Schemata.
Wie überprüfe ich, ob eine Anfrage von Level stammt? Legen Sie ein Secret für den Webhook fest. Level fügt einen X-Level-Signature Header formatiert als sha256=<hex_digest> für jeden Header-Wert. Berechnen Sie HMAC-SHA256 des rohen Anfrage-Bodys mit Ihrem Secret, und vergleichen Sie ihn dann mit dem Header-Wert. Siehe Anfrage-Signaturen überprüfen oben.
Wer kann Webhooks erstellen und verwalten? Die Webhook-Konfiguration – einschließlich des Anfragenprotokolls – ist auf Administratoren beschränkt. Nur Techniker mit Administratorzugriff auf Ihre Level-Organisation können Webhooks erstellen, bearbeiten, anzeigen oder löschen.
Alle meine Anfragen werden als fehlgeschlagen angezeigt. Was sollte ich überprüfen? Öffnen Sie eine fehlgeschlagene Anfrage im Detailfeld und lesen Sie die Fehlermeldung und den Antwort-Body. Häufige Ursachen: Die URL ist nicht öffentlich erreichbar, Ihr Endpunkt hat einen Nicht-2xx-Statuscode zurückgegeben oder die URL wurde falsch eingegeben. Beheben Sie das zugrunde liegende Problem und verwenden Sie dann Anfrage erneut ausführen um ohne Warten auf das automatische Wiederholungsfenster erneut zu versuchen.
Kann ich dieselben Ereignisse an mehrere Endpunkte senden? Ja. Erstellen Sie einen separaten Webhook für jede Ziel-URL. Jeder Webhook abonniert Ereignistypen unabhängig voneinander.
Was passiert nach 3 fehlgeschlagenen Zustellungsversuchen? Level hört auf zu wiederholen und protokolliert den endgültigen Fehlschlag. Der Webhook bleibt aktiviert und versucht weiterhin, zukünftige Ereignisse zuzustellen – nur diese spezifische Zustellung wird aufgegeben. Sie können sie dennoch manuell über den Tab „Anfragen" erneut ausführen.
Ich habe mein Webhook-Secret verloren. Kann ich es wiederherstellen? Nein. Das Secret kann nach dem Speichern des Webhooks nicht mehr eingesehen werden. Bearbeiten Sie den Webhook, um ein neues Secret festzulegen, und aktualisieren Sie dann Ihren Endpunkt-Code, um den neuen Wert zu verwenden.

Verwandte Artikel

DeskDay-Integration

ilert-Integration