Ereignisse per Abruf lesen: Änderungen an Vorgängen abholen statt empfangen

Nicht jedes Fremdsystem kann Nachrichten empfangen. Steht es hinter einer Firewall oder läuft es nur zu festen Zeiten, fragt es besser selbst nach, was sich seit seinem letzten Besuch geändert hat. Dafür stellt knooing dieselben Ereignisse, die ein Webhook bekommt, auch zum Abholen bereit. Das Fremdsystem merkt sich jeweils, bis wohin es gelesen hat, und holt beim nächsten Mal genau den Rest.

Julia Beispiel richtet in dieser Anleitung den Zugang für das Kalenderprogramm der Logistik ein, ein Fremdsystem. Es soll jeden neuen und geänderten Change erfahren. Die Schritte 1 und 2 erledigen Sie in knooing. Die Schritte 3 und 4 richtet die Person ein, die das Fremdsystem betreut; geben Sie ihr diese Anleitung weiter. Wie knooing Ereignisse stattdessen aktiv schickt, steht in Webhooks einrichten.

Die wichtigsten Begriffe

• Ereignis: etwas, das an einem Vorgang passiert ist, zum Beispiel ein neuer Change. In der Antwort steht es als technischer Name, hier change.created. Welcher Name zu welchem Ereignis gehört, zeigt die Tabelle in Webhooks einrichten.
• Abruf: Das Fremdsystem fragt selbst bei knooing nach, statt Nachrichten zu empfangen.
• Lesemarke: merkt sich, bis wohin das Fremdsystem gelesen hat. In der App heißt sie Cursor. knooing gibt sie in jeder Antwort als nextCursor mit. Beim nächsten Abruf schickt das Fremdsystem sie als since zurück und bekommt nur, was danach kam. Den Wert muss niemand verstehen; er wird nur gespeichert und unverändert zurückgegeben.
• Aufbewahrung: knooing hält Ereignisse 30 Tage bereit. Wer länger nicht abruft, verpasst Ereignisse.
• Beginn der Aufzeichnung: knooing speichert Ereignisse erst, wenn jemand sie abholt oder empfängt. Das ist ab einem passenden Schlüssel der Fall (Ereignisse abrufen plus Lese-Berechtigung der Vorgangsart) oder ab einem aktiven Webhook. Ältere Änderungen gibt es nicht als Ereignis.
• Lese-Berechtigung: was der Schlüssel lesen darf, etwa Changes lesen. In Hinweisen und Meldungen der App heißt sie Lese-Scope.

In den Bildern markieren Zahlen, wo Sie klicken. (i) markiert, wo Sie etwas ablesen.

Schritt 1: Den Schlüssel anlegen

Klicken Sie unten in der Seitenleiste auf Einstellungen, links auf Integrationen und daneben auf Schnittstellen. Klicken Sie im Reiter Schlüssel rechts über der Liste auf Schlüssel anlegen. Tragen Sie bei Name (1) „Kalenderprogramm Logistik“ ein. Den Kanal lassen Sie auf Schnittstelle/Provider; er betrifft nur gemeldete Störungen. Unter Berechtigungen sind zu Beginn Störungen melden (2) und Status eigener Meldungen abfragen (3) angehakt. Nehmen Sie beide Haken weg.

123

Scrollen Sie weiter und haken Sie Changes lesen (4) und Ereignisse abrufen (5) an.

45

Ganz unten unter Gültigkeit und Schutz steht das Feld für das Ablaufdatum. Tragen Sie ein Datum ein, höchstens ein Jahr ab heute, im Beispiel 15.10.2027. Danach kann das Fremdsystem nichts mehr abrufen; notieren Sie sich den Tag. Die übrigen Angaben dort lassen Sie, wie sie sind; was sie bedeuten, steht in Vorgänge, CMDB und Assets per Schnittstelle lesen. Klicken Sie dann unten auf Anlegen.

Warum zwei Berechtigungen? Ereignisse abrufen erlaubt den Abruf an sich. Welche Ereignisse kommen, bestimmen die Lese-Berechtigungen: Mit Changes lesen kommen nur Change-Ereignisse. Sollen auch Störungen kommen, haken Sie zusätzlich Störungen lesen an.

Beispiel: Das Kalenderprogramm zeigt geplante Arbeiten im Lager. Es braucht nur Changes.

Schritt 2: Den Schlüssel kopieren

Danach erscheint der Dialog Schlüssel angelegt. Klicken Sie auf Kopieren (1); der Knopf heißt danach Kopiert. Geben Sie den Schlüssel sicher an die Person weiter, die das Fremdsystem einrichtet, und klicken Sie auf Fertig.

1

Danach steht Kalenderprogramm Logistik in der Liste der Schlüssel, mit Status aktiv und bei Läuft ab dem 15.10.2027. Ab jetzt speichert knooing Change-Ereignisse für dieses Fremdsystem. Bei Zuletzt benutzt steht „noch nie“, bis der erste Abruf kommt; danach stehen dort Datum und Uhrzeit. So sehen Sie in knooing, ob das Fremdsystem abruft.

Warum ein eigener Schlüssel? Endet die Nutzung, widerrufen Sie genau diesen einen, ohne andere Anbindungen zu stören. Dazu klicken Sie in seiner Zeile auf Widerrufen und bestätigen die Rückfrage. Das lässt sich nicht rückgängig machen.

Beispiel: Tobias Beispiel, der das Kalenderprogramm betreut, trägt den Schlüssel dort ein.

Schritt 3: Die erste Lesemarke holen

Diesen und den nächsten Schritt richtet die Person ein, die das Fremdsystem betreut. In den Beispielen steht https://knooing.beispiel-gmbh.test für Ihre Basisadresse und $KNOOING_API_KEY für den Schlüssel. Die Basisadresse steht in knooing im Reiter Dokumentation im Abschnitt Anmeldung, im Beispiel https://knooing.beispiel-gmbh.test.

Beim ersten Abruf holt das Fremdsystem nur die Lesemarke, ohne alte Ereignisse:

curl 'https://knooing.beispiel-gmbh.test/api/v1/events?since=latest' \
  -H "X-API-Key: $KNOOING_API_KEY"

Die Antwort enthält eine leere Liste und die Lesemarke:

{
  "items": [],
  "nextCursor": "eyJ2IjoyLCJ4Ij…",
  "hasMore": false,
  "retentionDays": 30
}

Das Fremdsystem speichert den Wert von nextCursor. Lässt es since beim ersten Abruf weg, bekommt es alle gespeicherten Ereignisse, höchstens 30 Tage alte. Bei einem neuen Schlüssel sind das meist nur die seit Schritt 2.

Warum mit latest beginnen? Ein neues Fremdsystem soll meist nicht mit alten Ereignissen starten. Mit since=latest beginnt es beim heutigen Stand.

Beispiel: Das Kalenderprogramm holt am Montagmorgen seine erste Lesemarke.

Schritt 4: Neue Ereignisse abholen

Danach fragt das Fremdsystem in festen Abständen nach, zum Beispiel alle fünf Minuten, und schickt die gespeicherte Lesemarke mit:

curl "https://knooing.beispiel-gmbh.test/api/v1/events?since=<nextCursor>&limit=50" \
  -H "X-API-Key: $KNOOING_API_KEY"

<nextCursor> ersetzt es samt spitzer Klammern durch den gespeicherten Wert, am sichersten URL-kodiert, wie bei Werten in Adressen üblich. In items stehen jetzt die Ereignisse seit dem letzten Abruf, die ältesten zuerst. Gekürzt sieht die Antwort so aus:

{
  "items": [
    {
      "id": "cmv9ktxdi00vwexymwfr1645l",
      "event": "change.created",
      "ticketType": "change",
      "occurredAt": "2026-10-15T13:30:46.620Z",
      "ticket": {
        "number": "CHG-2026-000004",
        "status": "new",
        "priority": "Mittel - Arbeit ist möglich",
        "service": { "name": "Warenwirtschaft" }
      }
    }
  ],
  "nextCursor": "eyJ2IjoyLCJ4Ij…",
  "hasMore": false,
  "retentionDays": 30
}

Das Fremdsystem verarbeitet die Ereignisse und speichert danach den neuen nextCursor. Steht hasMore auf true, liegen weitere bereit; es ruft dann sofort noch einmal ab. Zeitangaben wie occurredAt stehen in Weltzeit (UTC), erkennbar am Z: 13:30 UTC ist im Beispiel 15:30 Uhr deutscher Sommerzeit.

Mit type grenzt das Fremdsystem auf Vorgangsarten ein: incident, service_request, change oder problem. Mit event, etwa event=change.created, grenzt es auf einzelne Ereignisse ein; die Namen stehen in Webhooks einrichten. Mehrere Werte trennt ein Komma. limit erlaubt bis zu 200 Ereignisse je Abruf. Wie oft das Fremdsystem abrufen darf, steht am Schlüssel bei Anfragen je Minute; vorgegeben sind 60.

Warum die Kennung id? Ein Ereignis kann ausnahmsweise zweimal kommen, etwa wenn ein Abruf abbrach, bevor die neue Lesemarke gespeichert war. Das Fremdsystem merkt sich deshalb die id und verarbeitet jedes Ereignis nur einmal.

Beispiel: Julia Beispiel legt einen Change für neue Scanner im Wareneingang an. Beim nächsten Abruf steht er als change.created mit der Nummer CHG-2026-000004 im Kalenderprogramm.

Wenn etwas nicht klappt

Die Schnittstelle antwortet bei Fehlern mit einem Statuscode und einer Meldung in error:

• 400 „since ist kein gültiger Cursor. Verwenden Sie den Wert nextCursor der letzten Antwort.“ Die Lesemarke wurde verändert oder abgeschnitten. Speichern Sie den Wert von nextCursor vollständig und schicken Sie ihn unverändert zurück.
• 410 mit dem Code cursor_expired. Die Lesemarke ist älter als 30 Tage; dazwischen können Ereignisse fehlen. Gleichen Sie den Stand über die Liste der Vorgänge mit updatedSince ab, wie in Vorgänge, CMDB und Assets per Schnittstelle lesen beschrieben. Beginnen Sie danach mit since=latest neu.
• 403 „Dem Schlüssel fehlt die Berechtigung "tickets.problem:read".“ Das Fremdsystem hat mit type eine Vorgangsart angefragt, die der Schlüssel nicht lesen darf; tickets.problem:read heißt im Dialog Probleme lesen. Lassen Sie den Filter weg oder legen Sie einen Schlüssel mit der Berechtigung an.
• 403 „Dem Schlüssel fehlt ein Lese-Scope für Vorgänge (tickets.<art>:read).“ Lese-Scope heißt Lese-Berechtigung. Der Schlüssel hat Ereignisse abrufen, aber keine Lese-Berechtigung einer Vorgangsart wie Changes lesen. Legen Sie einen Schlüssel mit beidem an.
• 401 „Ungültiger oder fehlender API-Schlüssel.“ Der Schlüssel fehlt im Kopfeintrag X-API-Key, ist falsch, widerrufen oder abgelaufen. Das passiert auch, wenn das Konto der Person gesperrt wird, die ihn angelegt hat. Prüfen Sie ihn in der Liste der Schlüssel. Legen Sie Schlüssel nicht mit dem Konto einer Person an, die das Unternehmen bald verlässt.
• 429 „Zu viele Anfragen mit diesem Schlüssel. Bitte später erneut versuchen.“ Das Fremdsystem ruft öfter ab, als Anfragen je Minute erlaubt. Lassen Sie es seltener abrufen.
• Der Schlüssel ging verloren, bevor er kopiert war. Er lässt sich nicht erneut anzeigen. Widerrufen Sie ihn in der Liste und legen Sie einen neuen an.
• „Für diese Änderung ist eine Zwei-Faktor-Anmeldung nötig. …“ Richten Sie in Ihrem Profil die Zwei-Faktor-Anmeldung ein oder melden Sie sich erneut damit an.
• Bei Zuletzt benutzt steht weiter „noch nie“. Das Fremdsystem ruft nicht ab, oder es schickt einen falschen Schlüssel oder eine falsche Adresse. Lassen Sie Schlüssel und Basisadresse im Fremdsystem prüfen.
• Die Liste bleibt leer. Seit dem letzten Abruf ist nichts passiert, oder die Person, die den Schlüssel angelegt hat, sieht die betroffenen Vorgänge nicht. Prüfen Sie in knooing, ob sich ein passender Vorgang geändert hat, und ob die Person ihn öffnen kann.