Wie lege ich einen Webhook an?

Diese Anleitung zeigt Schritt für Schritt, wie Sie in KentixONE einen Webhook erstellen. Sie erfahren, welche Felder es gibt, wann welche Option sinnvoll ist und wie Sie Testdaten senden. Für eine Übersicht der verfügbaren Variablen finden Sie unten einen Verweis auf die Webhook‑Referenz.

Voraussetzungen

• Zugriff auf die KentixONE Weboberfläche mit Administratorrechten
• Ziel‑Endpoint (URL) des externen Dienstes, der die Anfrage empfangen soll
• Optional: Zugangsdaten für Basic‑Auth oder ein Bearer‑Token, falls Ihr Endpoint Authentifizierung erfordert

Übersicht

• Ein Webhook ist eine HTTP‑Anfrage, die KentixONE bei einem Ereignis (z. B. Alarm, Benutzeraktion) an eine von Ihnen definierte URL sendet.
• Sie bestimmen Methode (GET/POST/PUT/PATCH/DELETE), Inhaltstyp und den genauen Dateninhalt (Payload).
• Variablen wie z. B. Alarm‑ oder Benutzerwerte können in die Daten eingefügt werden. Diese Variablen ersetzt KentixONE bei der Auslösung automatisch.

Schritt-für-Schritt-Anleitung

1. Webhook‑Übersicht öffnen

• Navigieren Sie zu: Konfiguration → Webhooks.
• In der Tabelle sehen Sie vorhandene Einträge und können neue Webhooks anlegen.

2. Neuen Webhook anlegen

• Klicken Sie auf „Webhook anlegen“.
• Aktiv: Schalten Sie den Webhook ein, wenn er sofort nutzbar sein soll.
• Name: Vergeben Sie einen sprechenden Namen.
• URL: Tragen Sie den vollständigen Ziel‑Endpoint ein (https://…)

3. HTTP‑Methode wählen

• Wählen Sie die gewünschte Methode.
• Verfügbare Optionen sind POST, GET, PUT, PATCH, DELETE.

hinweis

Zum Versenden von Daten wird üblicherweise eine POST-Anfrage verwendet.

4. Authentifizierung konfigurieren (optional)

• Keine Authentifizierung: Für frei erreichbare Endpunkte.
• Basic Auth: KentixONE sendet Benutzername/Passwort im Authorization‑Header (Base64).
• Bearer Token: KentixONE sendet das Token im Authorization‑Header.

info

Die KentixONE SmartAPI verwendet die Bearer Token Authentifizierung.

5. Inhaltstyp/Content Type festlegen

• Unterstützt werden text/plain, application/json oder application/xml.
• Wählen Sie den Inhaltstyp passend zum Zielsystem.

info

Für die KentixONE SmartAPI ist der Content Type application/json zu wählen.

6. Nutzdaten (Payload) definieren

Tragen Sie den Body passend zum Inhaltstyp ein. Ein Beispiel für JSON:

{
  "eventId": "$ALARM_EVENT_ID$",
  "sensor": "$ACTIVE_ALARM_SENSOR_NAME$",
  "status": "$ACTIVE_ALARM_ALARM_VALUE$",
  "value": "$ACTIVE_ALARM_MEASUREMENT_VALUE$",
  "user": {
    "id": "$USER_ID$",
    "name": "$USER_FULLNAME$",
    "mail": "$USER_MAIL$"
  },
  "timestamp": "$DATE_TIME$"
}

tipp

Eine vollständige Liste der möglichen Variablen finden Sie im Manual der Benutzeroberfläche unter Webhooks

7. Speichern und testen

• Speichern Sie den Webhook.
• Nutzen Sie „Webhook testen“, um eine Beispielanfrage sofort an Ihren Endpoint zu senden.
• Prüfen Sie Antwortcode und Logs Ihres Zielsystems.

info

Erfolgreiche Anfragen liefern in der Regel einen HTTP-Antwortcode im Bereich 200.

8. Webhook zuweisen

Nun kann der Webhook in den Konfigurationsmasken von Alarmgruppen und Sensoren (z.B. MultiSensoren) als Event-Handler verwendet werden.

Tipps & Tricks

• Nutzen Sie Test‑Endpoints (z. B. webhook.site, Request Bin) während der Einrichtung, um Payload und Header einfach prüfen zu können.
• Achten Sie auf korrektes Escaping von Anführungszeichen und Sonderzeichen in der Payload.
• Hinterlegen Sie Versionshinweise im Namen, wenn Sie das Schema später erweitern möchten (z. B. „Alarm‑Webhook v2“).

Fehlerbehebung

Fehler	Mögliche Ursache
401 Unauthorized 403 Forbidden	Prüfen Sie Authentifizierung (Basic/Bearer) und Berechtigungen im Zielsystem.
404 Not Found oder Timeout	URL falsch oder Ziel nicht erreichbar (Firewall/Proxy/DNS).
422 Unprocessable Entity	Stimmt der Content‑Type mit dem Payload überein (z. B. JSON)?
Variablen werden nicht ersetzt	Schreibweise exakt gemäß Referenz verwenden; der Austausch erfolgt erst zur Laufzeit bei der Auslösung.

Glossar

Begriff	Definition
Webhook	HTTP‑Callback, der bei Ereignissen Daten an einen Endpoint sendet.
Endpoint	Ziel‑Adresse (URL), die Anfragen entgegennimmt.
Content‑Type	Kennzeichnet das Datenformat des Bodys (z. B. application/json).
Header	Metadaten einer HTTP‑Anfrage (z. B. Authorization).
Payload/Body	Nutzdaten der Anfrage.