Wie erstelle ich für Enginsight Alarme eigene Webhook-Payloads mit dynamischen Platzhaltern?

Webhooks bieten dir die Möglichkeit, Alarme mit Drittanbieter-Anwendungen zu verknüpfen, um Benachrichtigungen auch außerhalb der Enginsight Plattform, z.B. in einem Messenger oder externen Ticketsystem, erhalten zu können.

Dabei sendet Enginsight eine HTTP-Anfrage (typischerweise POST) an die angegebene Webhook-URL und übermittelt darin einen Payload, also einen spezifischen Inhalt, im JSON-Format.

Mehr Informationen, wie du in der Enginsight Plattform einen Webhook erstellst, findest du im Enginsight Handbuch: Webhook hinzufügen.

---

Benutzerdefinierte Payloads mit dynamischen Platzhaltern

Du hast beim Hinzufügen eines Webhooks in der Enginsight Plattform die Möglichkeit, einen benutzerdefinierten Payload anzugeben, in dem du dynamische Platzhalter verwenden kannst.

Beim Auslösen eines Alarms, für den ein Webhook definiert wurde, ersetzt Enginsight diese Platzhalter mit den tatsächlichen Werten, bevor die HTTP-Anfrage an die angegebene Webhook-URL gesendet wird.

Verfügbare Platzhalter

Enginsight stellt folgende Platzhalter zur Verfügung:

Platzhalter	Daten-Typ	Beschreibung
alert_id	String	Eindeutige Kennung des Alarms
alert_name	String	Bezeichnung des Alarms
alert_severity	String	Kritikalität des Alarms
issue_id	String	Eindeutige Kennung des Vorkommnisses (Auffälligkeit / Issue oder Vorfall / Incident), das durch den Alarm ausgelöst wurde
organisation_id	String	Eindeutige Kennung der Organisation, die der Alarm betrifft
organisation_name	String	Name der Organisation, die der Alarm betrifft
platform	String	URL, unter der die Enginsight Plattform aufgerufen werden kann
reference_conditions[x].groups['key']	String	Wert eines Felds in einem SIEM-Workflow: x muss ein Integer-Wert sein 'key' muss dem Feldnamen entsprechen, wie er im Workflow angegeben ist, z.B. 'gen.username' Bitte beachte: Dieser Platzhalter ist ausschließlich für die Alarmart Workflow (SIEM) verfügbar.
reference_displayName	String	Anzeigename des Objekts, für das der Alarm gilt
reference_id	String	Eindeutige Kennung des Objekts, für das der Alarm gilt
reference_severity	String	Schweregrad eines SIEM-Workflows Bitte beachte: Dieser Platzhalter ist ausschließlich für die Alarmart Workflow (SIEM) verfügbar.
reference_type	String	Art des Objekts, für das der Alarm gilt

---

Struktur eines Payloads mit Platzhaltern

Es müssen folgende Bedingungen erfüllt sein, damit Enginsight verwendete Platzhalter korrekt ersetzen und die HTTP-Anfrage an die Webhook-URL senden kann:

• Der Payload muss in gültigem JSON vorliegen.

• Platzhalter müssen in doppelte geschweifte Klammern {{...}} gesetzt werden, z.B. {{alert_severity}}.

• Wenn dein Zielsystem Strings erwartet, müssen die Platzhalter zusätzlich in doppelte Anführungszeichen "{{...}}" gesetzt werden, z.B. "{{alert_severity}}".

• Wenn dein Zielsystem Zahlen oder Boolesche Werte erwartet, müssen die doppelten Anführungszeichen nur dann gesetzt werden, wenn dein Zielsystem zusätzlich auch Strings akzeptiert.

Die Namen der JSON-Keys selbst sind frei wählbar.

---

Beispiele für benutzerdefinierte Payloads

In den folgenden Beispiel-Payloads gehen wir davon aus, dass du ein externes Ticketsystem verwendest. Dieses erwartet beim Erstellen eines Tickets für einen in der Enginsight Plattform ausgelösten Alarm den Wert severity.

Dies bedeutet, dass du in deinen benutzerdefinierten Payloads den Platzhalter {{alert_severity}} verwenden musst, um die Dringlichkeit eines ausgelösten Alarms mitzugeben oder den Platzhalter {{reference_severity}}, um den Schwergrad eines SIEM-Workflows mitzugeben.

Beispiel 1: Angabe der Kritikalität eines Alarms als eigenes Key-Value-Paar

{ 
"severity": "{{alert_severity}}", 
"alert_id": "{{alert_id}}", 
"title": "{{alert_name}}" 
}

Beispiel 2: Angabe der Kritikalität eines Alarms innerhalb eines benutzerdefinierten Texts

{ 
"issue_id": "{{issue_id}}", 
"description": "Der Alarm {{alert_name}} hat den Schweregrad {{alert_severity}}." 
}

Beispiel 3: Angabe des Schweregrades eines SIEM-Workflows

{
"title": "{{alert_name}}",
"severity": "{{reference_severity}}",
"username": "{{reference_conditions[0].groups['gen.username']}}",
"hostname": "{{reference_conditions[0].groups['gen.hostname']}}"
}

---

Standard-Templates für Webhook-Payloads

Wenn du keinen vollständig benutzerdefinierten Payload angeben möchtest, kannst du auch eines der Standard-Templates nutzen und JSON-Keys sowie dynamische Platzhalter entsprechend ergänzen.

Mehr Informationen, welche Standard-Templates für Webhook-Payloads es gibt, findest du in der Knowledge Base: Welche Standard-Templates für Webhook-Payloads gibt es bei Enginsight Alarmen?

---