Report monitoring events via the interface: alarm, all-clear and response

Dieser Artikel richtet sich an Personen, die ein Überwachungswerkzeug anbinden. Er zeigt, was das Werkzeug senden muss und was knooing antwortet. Was knooing mit den Meldungen macht, steht in Monitoring-Ereignisse bündeln und Vorgänge automatisch aus Monitoring-Ereignissen anlegen.

Ein Ereignis legt in knooing nie direkt einen Vorgang an. Es landet als Zeile im Eingangsbuch (Kanal Monitoring). Ob daraus ein Vorgang wird, entscheidet allein die Korrelation. Die Einstellung Vorgang sofort anlegen (Auto-Anlage) des Schlüssels gilt für Monitoring-Ereignisse nicht.

Schritt 1: Einen Schlüssel für die Überwachung anlegen

Legen Sie unter Einstellungen, Integrationen, Schnittstellen im Reiter Schlüssel über Schlüssel anlegen einen eigenen Schlüssel für das Überwachungswerkzeug an, zum Beispiel mit dem Namen Überwachung Rechenzentrum. Wählen Sie als Berechtigung nur Monitoring-Ereignisse einliefern. Das Werkzeug sendet den Schlüssel bei jedem Aufruf im Kopffeld X-API-Key.

Warum ein eigener Schlüssel? Wird er bekannt oder wechselt der Anbieter, sperren Sie genau diesen einen Zugang. Außerdem gilt die Alarm-Kennung je Schlüssel: Zwei Werkzeuge mit derselben Kennung stören sich nicht.

Schritt 2: Einen Alarm melden

Das Werkzeug sendet eine POST-Anfrage an /api/v1/monitoring/events. Die Adresse Ihres knooing-Systems steht in der Dokumentation unter Schnittstellen. Im Text steht <Adresse Ihres knooing-Systems> stellvertretend.

curl -X POST '<Adresse Ihres knooing-Systems>/api/v1/monitoring/events' \
  -H 'X-API-Key: <Ihr Schlüssel>' \
  -H 'Content-Type: application/json' \
  --data '{
    "externalId": "alm-1001",
    "source": "Überwachung Rechenzentrum",
    "summary": "Antwortzeit der Webseite über 3 Sekunden",
    "severity": "medium",
    "ciKey": "CI-SRV-02",
    "occurredAt": "2026-10-09T13:20:00Z"
  }'

Die Felder:

• summary (Pflicht, bis 500 Zeichen): die Meldung als Text.
• severity (Pflicht): critical, high, medium oder low.
• Objektbezug (mindestens eines Pflicht): ciKey (die Nummer des Configuration Items), serviceId, serviceExternalId, hostname, ipAddress oder alias. Ohne Bezug lässt sich das Ereignis keinem Objekt zuordnen.
• externalId (empfohlen, bis 200 Zeichen): die Alarm-Kennung Ihres Werkzeugs. Sie macht Wiederholungen erkennbar und ist Voraussetzung für die Entwarnung.
• source (bis 200 Zeichen): der Name des Werkzeugs, nur zur Anzeige.
• description (bis 20.000 Zeichen) und occurredAt (ISO-8601-Zeitpunkt, ohne Angabe gilt „jetzt").

tenantId und tenantSlug lassen Sie weg. Nennen sie einen anderen Mandanten als den des Schlüssels, lehnt die Schnittstelle mit 400 und dem Code tenant_mismatch ab. Der Körper darf höchstens 256 KB groß sein.

Warum Objektbezug und Kennung? Ohne Bezug weiß knooing nicht, welches System betroffen ist, und kann weder bündeln noch den Servicedesk richtig adressieren. Ohne Kennung kann das Werkzeug später keine Entwarnung zuordnen.

Schritt 3: Die Antwort auswerten

Bei Erfolg antwortet knooing mit 201:

{
  "intakeId": "…",
  "deduplicated": false,
  "ciResolved": true,
  "serviceResolved": true,
  "linkStatus": "resolved",
  "linkFindings": [],
  "linkReviewOpen": false,
  "clusterId": "…",
  "correlationDepth": 0,
  "autoIncidentCreated": false
}

• intakeId: die Eingangszeile dieses Ereignisses.
• ciResolved, serviceResolved: ob sich Objekt und Service in Ihrem Mandanten auflösen ließen.
• linkStatus, linkFindings, linkReviewOpen: Stand der Zuordnung von Objekt zu Service. Ist sie nicht eindeutig, steht needs_review, und der Servicedesk klärt den Fall im Eingangsbuch.
• clusterId: der Cluster, zu dem das Ereignis gehört. Fehlt er (null), ist die Korrelation aus.
• correlationDepth: die Beziehungsebene der Zuordnung: 0 ist dasselbe Objekt, 1 ein direkter Nachbar, 2 und höher entferntere. Der Weg dorthin steht bewusst nicht in der Antwort, denn er enthält Schlüssel aus der Konfigurationsverwaltung.
• autoIncidentCreated: true, wenn dieses Ereignis die Schwelle erreicht und einen Vorgang angelegt hat. Dann steht zusätzlich ticketNumber in der Antwort.

Warum so viele Felder? Ihr Werkzeug kann damit zum Beispiel die Vorgangsnummer an den Alarm anheften oder Meldungen mit ciResolved: false zur Pflege der Objektnummern anzeigen.

Schritt 4: Wiederholungen gefahrlos senden

Sendet das Werkzeug denselben Alarm mit derselben externalId noch einmal, entsteht nichts Neues. knooing antwortet mit 200:

{ "intakeId": "…", "deduplicated": true, "intakeStatus": "linked_to_ticket" }

intakeStatus nennt den Stand der Eingangszeile. Ist die externalId bereits anderweitig belegt, etwa durch eine Meldung der Incident-Schnittstelle mit demselben Schlüssel, antwortet knooing mit 409 und dem Code conflict.

Warum? Netzwerke verlieren Antworten. Das Werkzeug muss im Zweifel einfach nochmals senden dürfen, ohne dass doppelte Zeilen oder Vorgänge entstehen.

Schritt 5: Die Entwarnung melden

Wird der Alarm im Werkzeug erledigt, meldet es das mit dem Feld status. Erlaubt sind zwei Werte:

• alarm (Standard, wenn das Feld fehlt): ein neuer Alarm. Auch firing und problem gelten als Alarm.
• ok: die Entwarnung. Auch resolved, clear, cleared, recovery und recovered gelten als Entwarnung.

Bei ok genügt die externalId des Alarms, der entwarnt wird, mit demselben Schlüssel gesendet. Objektbezug, severity und Messwerte sind nicht nötig. source, summary und occurredAt sind optional.

curl -X POST '<Adresse Ihres knooing-Systems>/api/v1/monitoring/events' \
  -H 'X-API-Key: <Ihr Schlüssel>' \
  -H 'Content-Type: application/json' \
  --data '{
    "status": "ok",
    "externalId": "alm-1001",
    "source": "Überwachung Rechenzentrum"
  }'

Eine Entwarnung legt nie eine neue Eingangszeile oder einen Vorgang an. Die Antwort ist immer 200:

{
  "cleared": true,
  "matched": true,
  "action": "noticed",
  "alreadyCleared": false,
  "intakeId": "…",
  "ticketNumber": "INC-2026-000006",
  "alarmsCleared": 3,
  "alarmsTotal": 3
}

• action sagt, was geschah: recorded (die Entwarnung ist vermerkt, es sind aber noch nicht alle Alarme des Vorgangs entwarnt, oder der Alarm hat keinen Vorgang), noticed (alle Alarme entwarnt, die Zuständigen bekamen einen Hinweis), auto_resolved (alle Alarme entwarnt und der Vorgang wurde automatisch gelöst), already_cleared (Wiederholung, nichts passiert) oder unmatched (kein Alarm mit dieser Kennung bekannt, die Entwarnung wurde protokolliert und verworfen).
• alarmsCleared und alarmsTotal zählen nur mit Vorgang: wie viele der Alarme des Vorgangs entwarnt sind.
• cleared und matched sind false bei unmatched.

Was die Entwarnung im Servicedesk auslöst, ist je Mandant eingestellt (Bei Entwarnung der Überwachung, siehe Vorgänge automatisch aus Monitoring-Ereignissen anlegen).

Warum immer 200? Für das Werkzeug ist eine Entwarnung zu einem unbekannten Alarm kein Fehler, sondern nur nichts zu tun. Mit action und matched sieht es trotzdem, was geschah.

Wenn etwas nicht klappt

• 401 „Ungültiger oder fehlender API-Schlüssel.": Das Kopffeld X-API-Key fehlt, der Schlüssel ist widerrufen oder abgelaufen, oder die Berechtigung Monitoring-Ereignisse einliefern fehlt.
• 403 feature_disabled „Der Servicedesk ist für diesen Mandanten nicht aktiviert.": Der Servicedesk ist für den Mandanten nicht freigeschaltet.
• 400 „summary ist Pflicht.": Das Feld summary fehlt oder ist leer.
• 400 „severity muss eines von critical, high, medium, low sein.": Der Schweregrad hat einen anderen Wert.
• 400 „Mindestens eines von ciKey, serviceId, serviceExternalId, hostname, ipAddress oder alias ist Pflicht …": Das Ereignis nennt kein Objekt.
• 400 „status muss "alarm" oder "ok" sein.": Das Feld status hat einen anderen Wert.
• 400 „Bei status "ok" ist externalId Pflicht: die Kennung des Alarms, der entwarnt wird.": Die Entwarnung braucht die Kennung des Alarms.
• 400 tenant_mismatch: tenantId oder tenantSlug im Körper nennen einen anderen Mandanten. Lassen Sie die Felder weg.
• 409 conflict „Die Kennung ist bereits vergeben.": Die externalId gehört zu einer anderen Meldung.
• 413 „Der Körper ist größer als 256 KB.": Senden Sie weniger Daten je Aufruf.
• 429: Der Schlüssel hat seine Anfragen je Minute überschritten. Warten Sie und senden Sie später.