Einführung
Konfigurieren Sie HTTP-Rückrufe, um Level-Ereignisse in Echtzeit an Ihre eigenen Systeme zu übertragen. Wenn etwas in Level geschieht — eine neue Warnung wird ausgelöst, ein Gerät wird hinzugefügt, eine Gruppe wird aktualisiert — sendet Level eine POST-Anfrage an die URL, die Sie angeben, damit Sie in Ihren eigenen Tools darauf reagieren können, ohne die API abzufragen.
Eine vollständige API-Referenz und Nutzlast-Schemas pro Ereignis finden Sie in der Level-Entwicklerdokumentation.
⚙️ VORAUSSETZUNGEN
Ein öffentlich zugänglicher HTTPS-Endpunkt, der POST-Anfragen mit JSON-Body empfangen kann.
Administratorzugriff auf Ihre Level-Organisation.
Webhook-Einstellungen
Navigieren Sie zu Einstellungen → Webhooks . Die Seite hat zwei Registerkarten:
Webhooks — Ihre konfigurierten Webhooks
Anfragen — das Lieferprotokoll für alle ausgehenden Anfragen
Erstellen eines Webhooks
1. Klicken Sie auf + Webhook hinzufügen (oben rechts) oder + Webhook erstellen (leerer Zustand).
2. Geben Sie die Ziel- URL ein. Dies ist die Stelle, an die Level Ereignisdaten senden wird. Verwenden Sie HTTPS.
3. (Optional) Geben Sie ein Geheimnis ein. Level verwendet dies, um jede ausgehende Anfrage zu signieren, damit Ihr Endpunkt überprüfen kann, dass die Nutzlast von Level stammt.
💡 TIPP: Generieren Sie Ihr Geheimnis mit einem Passwort-Manager oder openssl rand -hex 32. Verwenden Sie eine hochwertige Zufallszeichenfolge.
⚠️ WARNUNG: Das Geheimnis kann nach dem Speichern nicht mehr angezeigt werden. Kopieren Sie es, bevor Sie auf Webhook hinzufügen klicken — Sie benötigen es in Ihrem Endpunkt-Code, um Signaturen zu überprüfen.
4.. Der Aktiviert Schalter ist standardmäßig aktiviert. Lassen Sie ihn aktiviert, um sofort Ereignisse zu empfangen. Deaktivieren Sie ihn, um die Lieferung zu pausieren, ohne den Webhook zu löschen.
5. Unter Zu sendende Ereignisse , wählen Sie, was diesen Webhook auslöst:
Alle Ereignistypen senden — Level sendet jeden Ereignistyp, einschließlich neuer in der Zukunft.
Typen zum Senden auswählen — wählen Sie aus der untenstehenden Liste.
Verfügbare Ereignistypen
Ereignis | Wenn es ausgelöst wird |
Warnung aktiv | Eine neue Warnung wird auf einem Gerät ausgelöst |
Warnung gelöst | Eine bestehende Warnung wird gelöst |
Gerät erstellt | Ein neues Gerät wird zu Ihrem Konto hinzugefügt |
Gerät gelöscht | Ein Gerät wird aus Ihrem Konto entfernt |
Gerät aktualisiert | Die Daten oder Konfiguration eines bestehenden Geräts ändert sich |
Gruppe erstellt | Eine neue Gerätegruppe wird erstellt |
Gruppe gelöscht | Eine Gerätegruppe wird dauerhaft gelöscht |
Gruppe aktualisiert | Der Name oder die Konfiguration einer Gruppe wird geändert |
ℹ️ HINWEIS: Wenn Sie Typen zum Senden auswählen verwenden, werden neue Ereignistypen, die in der Zukunft zu Level hinzugefügt werden, nicht automatisch einbezogen. Wechseln Sie zu Alle Ereignistypen senden , wenn Sie zukunftskompatible Lieferung möchten.
6. Klicken Sie auf Webhook hinzufügen zum Speichern.
Nutzlaststruktur
Jede Webhook-Lieferung — unabhängig vom Ereignistyp — verwendet dieselbe JSON-Hülle:
{
"event_type": "device_created",
"event_id": "a3f1b2c4-...",
"occurred_at": "2026-03-13T18:30:00Z",
"data": { ... }
}
Feld | Typ | Beschreibung |
| Zeichenfolge | Einer der 8 oben aufgelisteten Ereignistypen |
| UUID | Eindeutig pro Ereignis; stabil über Wiederholungen — verwenden Sie dies zum Deduplizieren |
| ISO 8601 Datetime (UTC) | Wenn das Ereignis generiert wurde |
| Objekt | Ressourcenspezifische Nutzlast für dieses Ereignis |
💡 TIPP: Verwenden Sie event_id um Ihren Endpunkt idempotent zu machen. Level wiederholt fehlgeschlagene Lieferungen automatisch, daher kann dasselbe Ereignis mehr als einmal ankommen.
ℹ️ HINWEIS: Für vollständige Schemas pro Ereignis data, siehe Level-Entwicklerdokumentation.
Überprüfung von Anfrage-Signaturen
Wenn Sie ein Geheimnis konfiguriert haben, Level enthält einen X-Level-Signature Header auf jeder Anfrage. Das Format ist sha256=<hex_digest>.
Zur Überprüfung:
Nehmen Sie den Raw-JSON-Anfragebody als Zeichenfolge.
Berechnen Sie
HMAC-SHA256dieser Zeichenfolge mit Ihrem Geheimnis als Schlüssel.Präfixieren Sie das Ergebnis mit
sha256=und vergleichen Sie es mit demX-Level-SignatureHeader-Wert.Wenn sie übereinstimmen, stammt die Anfrage von Level.
ℹ️ HINWEIS: Der X-Level-Signature Header ist nur vorhanden, wenn auf dem Webhook ein Geheimnis konfiguriert ist. Wenn Sie keins festgelegt haben, erwägen Sie, den Webhook zu bearbeiten, um eines hinzuzufügen.
Überprüfung der Lieferlogs
Die Anfragen Registerkarte zeigt jede ausgehende Anfrage, die Level über alle konfigurierten Webhooks versucht hat.
Jede Zeile zeigt:
Status — Erfolgs- oder Fehler-Abzeichen
Statuscode — der HTTP-Antwortkode von Ihrem Endpunkt (oder
--wenn die Verbindung vor einer Antwort fehlgeschlagen ist)URL — das Ziel für diese Anfrage
Klicken Sie auf eine beliebige Zeile, um das Detailpanel zu öffnen.
Das Detailpanel zeigt:
Ereigniszeit — wann das Ereignis aufgetreten ist
Statuscode — HTTP-Antwort von Ihrem Server
Vollständige URL — die genaue URL, die Level gesendet hat
Fehlermeldung — der Verbindungs- oder HTTP-Fehler, falls vorhanden
Antwortkörper — was Ihr Endpunkt zurückgegeben hat (oder die Raw-Fehlerausgabe)
Automatische Wiederholungen
Wenn eine Lieferung fehlschlägt, Level wiederholt automatisch — bis zu 3 Versuche insgesamt. Jeder Wiederholungsversuch wartet etwa 2 Minuten, plus eine zufällige Verzögerung von 1 bis 60 Sekunden. Nach 3 fehlgeschlagenen Versuchen hört Level auf zu versuchen und protokolliert den endgültigen Fehler. Es wird keine Warnung ausgelöst und der Webhook wird nicht deaktiviert.
ℹ️ HINWEIS: Weil Level automatisch wiederholt, kann dasselbe Ereignis mehr als einmal geliefert werden. Verwenden Sie event_id zum Deduplizieren auf Ihrer Seite.
Manuelle Wiederholung einer fehlgeschlagenen Anfrage
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 Ende des Detailpanels. Level sendet die ursprüngliche Nutzlast sofort erneut.
⚠️ WARNUNG: Anfrage erneut ausführen sendet dieselbe Nutzlast erneut. Wenn Ihr Endpunkt nicht idempotent ist, kann dies zu Duplikaten führen. Überprüfen Sie event_id vor der Verarbeitung.
Verwaltung bestehender Webhooks
Auf der Webhooks Registerkarte ist jeder konfigurierte Webhook mit seiner URL und seinem aktivierten Status aufgelistet. Von dort aus können Sie die Konfiguration bearbeiten, sie ein- oder ausschalten oder löschen.
ℹ️ HINWEIS: Das Deaktivieren eines Webhooks stoppt die Lieferung ohne ihn oder sein Anfrageverlauf zu löschen. Verwenden Sie dies, wenn Ihr Endpunkt gewartet wird.
FAQ
Welches Format verwendet Level für Webhook-Nutzlasten? Level sendet einen HTTP POST mit JSON-Body. Jedes Ereignis verwendet dieselbe Hülle:
event_type,event_id,occurred_at, unddata. DasdataObjekt enthält die ressourcenspezifische Nutzlast für diesen Ereignistyp. Siehe Level-Entwicklerdokumentation für vollständige Schemas pro Ereignis.Wie überprüfe ich, dass eine Anfrage von Level stammt? Legen Sie ein Geheimnis auf dem Webhook fest. Level enthält einen
X-Level-SignatureHeader, der alssha256=<hex_digest>formatiert ist, auf jeder Anfrage. Berechnen Sie HMAC-SHA256 des Raw-Anfragebody mit Ihrem Geheimnis, vergleichen Sie dann mit dem Header-Wert. Siehe Überprüfung von Anfrage-Signaturen oben.Wer kann Webhooks erstellen und verwalten? Die Webhook-Konfiguration — einschließlich des Anfragelogs — 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 zeigen "Fehlgeschlagen" an. Was sollte ich überprüfen? Öffnen Sie eine fehlgeschlagene Anfrage im Detailpanel und lesen Sie die Fehlermeldung und den Antwortkörper. Häufige Ursachen: Die URL ist nicht öffentlich erreichbar, Ihr Endpunkt hat einen Non-2xx-Statuscode zurückgegeben, oder die URL wurde falsch eingegeben. Beheben Sie das zugrunde liegende Problem, verwenden Sie dann Anfrage erneut ausführen zum Wiederholen, ohne auf das Fenster für automatische Wiederholung zu warten.
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.
Was passiert nach 3 fehlgeschlagenen Lieferversuchen? Level hört auf zu wiederholen und protokolliert den endgültigen Fehler. Der Webhook bleibt aktiviert und versucht weiterhin zukünftige Ereignisse — nur diese spezifische Lieferung wird aufgegeben. Sie können sie immer noch manuell über die Anfragen-Registerkarte erneut ausführen.
Ich habe mein Webhook-Geheimnis verloren. Kann ich es wiederherstellen? Nein. Das Geheimnis kann nach dem Speichern des Webhooks nicht angezeigt werden. Bearbeiten Sie den Webhook, um ein neues Geheimnis festzulegen, aktualisieren Sie dann Ihren Endpunkt-Code, um den neuen Wert zu verwenden.