Set up webhooks: report changes to incidents, changes and other tickets

Arbeitet ein Dienstleister mit einem eigenen Ticketsystem, soll es erfahren, sobald sich in knooing etwas tut: eine neue Störung, ein freigegebener Change, ein gelöstes Problem. Ein Webhook erledigt das. knooing schickt bei jedem gewählten Ereignis eine kurze Nachricht an eine Adresse des Fremdsystems. Jede Nachricht ist signiert. So kann der Empfänger prüfen, dass sie wirklich von knooing kommt.

Julia Beispiel richtet in dieser Anleitung einen Webhook für das Ticketsystem der Muster IT-Service GmbH ein. Es soll neben Störungen auch erfahren, wann ein Change angelegt, geändert oder freigegeben wird. Am Ende kommen die Nachrichten an, und das Zustellprotokoll zeigt jede Zustellung. Soll das Fremdsystem lieber selbst nachfragen, statt Nachrichten zu empfangen, lesen Sie Ereignisse per Abruf lesen.

Die wichtigsten Begriffe

• Fremdsystem: ein anderes Programm außerhalb von knooing, hier das Ticketsystem eines Dienstleisters.
• Vorgang: ein Eintrag im Servicedesk. Es gibt vier Arten: Störung (etwas funktioniert nicht), Service Request (eine Anfrage, etwa nach einem Zugang), Change (eine geplante Änderung) und Problem (die Ursache wiederkehrender Störungen).
• Webhook: eine Adresse beim Fremdsystem, an die knooing Nachrichten schickt, sobald etwas passiert. Technisch ist jede Nachricht eine HTTP-POST-Anfrage, also eine Sendung an diese Adresse.
• Ereignis: was passiert ist, zum Beispiel Change angelegt oder Störung gelöst. Sie wählen, welche Ereignisse der Webhook bekommt. Die Tabelle am Ende nennt zu jedem Ereignis den technischen Namen in der Nachricht.
• Secret: ein geheimer Wert, den nur knooing und der Empfänger kennen. Damit unterschreibt knooing jede Nachricht, und der Empfänger prüft die Unterschrift.
• Schlüsselbindung: Der Webhook gehört zu einem Schlüssel des Fremdsystems. Er bekommt dann nur Ereignisse zu Vorgängen, die dieser Schlüssel lesen darf. Ein Webhook, dessen Schlüssel Changes lesen darf, bekommt Change-Ereignisse, aber keine zu Problemen.
• Zustellung: ein Versuch, eine Nachricht zu übergeben. Die Zustände heißen zugestellt (angekommen), fehlgeschlagen (nicht angekommen, knooing versucht es erneut) und aufgegeben (nach 8 Versuchen nicht angekommen).
• HTTP-Code: die Antwort des Empfängers als Zahl. 200 heißt: angenommen. Mehr dazu unter „Wenn etwas nicht klappt“.
• Provider: in den Hinweisen der App ein anderes Wort für Dienstleister.
• Öffentliche Nachricht: ein Kommentar am Vorgang, den auch die meldende Person sieht. Interne Notizen schickt knooing nie.

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

Schritt 1: Die Webhooks öffnen

Klicken Sie unten in der Seitenleiste auf Einstellungen, links auf Integrationen und in der Spalte daneben auf Schnittstellen. Klicken Sie oben auf den Reiter Webhooks (1) und rechts auf Webhook anlegen (2). Der Hinweis über der Liste spricht nur von Störungen; derselbe Dialog meldet auch Changes, Service Requests und Probleme.

12

Danach öffnet sich der Dialog Webhook anlegen.

Warum ein Webhook und kein Export? Ein Export zeigt einen Stand. Ein Webhook meldet jede Änderung sofort. So arbeiten beide Seiten mit denselben Daten.

Beispiel: Die Muster IT-Service GmbH plant die Arbeiten an der Lagertechnik in ihrem eigenen Ticketsystem. Sie will freigegebene Changes sofort sehen.

Schritt 2: Name und Ziel-Adresse eintragen

Tragen Sie bei Name (1) ein, wer die Nachrichten bekommt, im Beispiel „Ticketsystem Muster IT-Service“. Bei Ziel-Adresse (URL) (2) tragen Sie die Adresse des Empfängers ein, im Beispiel https://tickets.muster-it-service.example/knooing/hooks.

12

Darunter stehen unter Ereignisse zuerst die Störungen. Ihre sechs Ereignisse sind vorab angehakt, von Störung angelegt bis Störung zugewiesen. Nehmen Sie die Haken weg, die der Empfänger nicht braucht. Welche das sind, sagt Ihnen die Person, die das Fremdsystem betreut.

Warum nur https? Die Nachrichten enthalten Vorgangsnummern, Status und Services. Über eine verschlüsselte Verbindung kann sie unterwegs niemand mitlesen.

Beispiel: Der Dienstleister soll weiterhin erfahren, was mit den Störungen geschieht, die sein Ticketsystem an knooing meldet. Julia Beispiel lässt die Störungs-Ereignisse angehakt.

Schritt 3: Ereignisse und Schlüssel wählen

Scrollen Sie im Dialog nach unten zu Changes. Haken Sie Change angelegt (1), Change: Status geändert (2) und Change: Freigabe erteilt (3) an. Wählen Sie bei Schlüssel (optional) den Schlüssel des Fremdsystems, im Beispiel Muster IT-Service Ticketabgleich (4).

Achtung: Die Bindung an einen Schlüssel lässt sich später nicht ändern. Haben Sie sich verwählt, legen Sie einen neuen Webhook an und löschen den alten. Obwohl das Feld „optional“ heißt, brauchen Changes, Service Requests und Probleme einen Schlüssel. Auch der Hinweis unter dem Feld nennt nur Störungen.

Unter dem Schlüssel steht der Schalter Nur eigene Meldungen dieses Schlüssels. Er gilt nur für Störungen und ist vorab an; darunter steht dann „An: …“.

• An: Der Dienstleister bekommt nur die Störungen, die sein System selbst über diesen Schlüssel an knooing gemeldet hat.
• Aus: Er bekommt alle Störungen Ihres Unternehmens.

Für Changes, Service Requests und Probleme spielt der Schalter keine Rolle; dort zählt, was der Schlüssel lesen darf. Klicken Sie unten auf Webhook anlegen (5).

12345

Warum ein Schlüssel? Über den Schlüssel weiß knooing, was der Empfänger sehen darf. Ohne ihn gingen Change-Ereignisse an eine Adresse, für die niemand Rechte festgelegt hat.

Beispiel: Der Schlüssel Muster IT-Service Ticketabgleich darf Changes lesen und Störungen melden. Julia Beispiel lässt Nur eigene Meldungen dieses Schlüssels an. Der Webhook bekommt die drei Change-Ereignisse und Nachrichten zu den Störungen, die der Dienstleister selbst gemeldet hat.

Schritt 4: Das Secret übergeben

Nach dem Klick auf Webhook anlegen öffnet sich der Dialog Webhook angelegt mit dem Secret. Klicken Sie auf Kopieren (1); der Knopf heißt danach Kopiert. Legen Sie das Secret sofort im Passwort-Tresor ab, etwa für die Person, die den Empfänger betreut. Klicken Sie erst dann auf Fertig.

1

Danach steht der Webhook in der Liste mit Status aktiv. Unter dem Namen steht der Anfang des Secrets, etwa whsec_b140f049…. Daran erkennen Sie, welches Secret gilt; das ganze Secret zeigt knooing nicht mehr. Bei Letzte Zustellung steht „noch nie“, bis die erste Nachricht ankommt. Fehlerserie 0 heißt: bisher kein Fehlschlag.

Der Inhalt einer Nachricht sieht für einen neuen Change so aus, gekürzt:

{
  "version": 1,
  "event": "change.created",
  "ticketType": "change",
  "occurredAt": "2026-10-15T13:27:32.792Z",
  "ticket": {
    "number": "CHG-2026-000003",
    "status": "new",
    "priority": "Mittel - Arbeit ist möglich",
    "service": { "name": "Warenwirtschaft" }
  }
}

Zeitangaben wie occurredAt stehen in Weltzeit (UTC), erkennbar am Z am Ende: 13:27 UTC ist im Beispiel 15:27 Uhr deutscher Sommerzeit. Werte wie status stehen in technischer Form, etwa new für neu. priority steht so, wie die Priorität in Ihrem knooing heißt.

Warum sofort kopieren? knooing zeigt das Secret nur jetzt. Geht es verloren, wählen Sie im Menü ⋯ ganz rechts in der Zeile Secret neu erzeugen und übergeben das neue Secret. Das bisherige gilt dann sofort nicht mehr.

Beispiel: Tobias Beispiel hinterlegt das Secret im Ticketsystem des Dienstleisters.

Schritt 5: Die Zustellung testen

Warten Sie, bis die Person beim Empfänger bestätigt, dass Adresse und Secret dort eingetragen sind. Klicken Sie dann in der Zeile des Webhooks auf Testzustellung (1). knooing schickt eine Probe-Nachricht mit dem Ereignis ping.

1

Danach erscheint unten auf der Seite für einige Sekunden die Meldung, dass die Testzustellung angekommen ist, darunter HTTP 200. Der Empfänger hat die Nachricht angenommen. Lautet die Meldung stattdessen „… fehlgeschlagen.“, hat der Empfänger nicht oder mit einem Fehler geantwortet. Was die Zahl darunter bedeutet, steht unter „Wenn etwas nicht klappt“.

Warum testen? Ein Tippfehler in der Adresse oder eine Sperre beim Empfänger fällt sonst erst auf, wenn wichtige Nachrichten fehlen.

Beispiel: Die Testzustellung kommt mit HTTP 200 an. Die Verbindung steht.

Schritt 6: Das Zustellprotokoll lesen

Klicken Sie in der Zeile des Webhooks ganz rechts auf ⋯ (drei Punkte). Es öffnet sich ein Menü mit Bearbeiten, Zustellprotokoll, Pausieren, Secret neu erzeugen und Löschen. Wählen Sie Zustellprotokoll. Es zeigt die letzten 50 Zustellversuche, den neuesten oben (i).

i

Jede Zeile nennt Zeitpunkt, Ereignis, Status, HTTP, Versuch, Fehler und Nächster Versuch. Im Beispiel kam der neue Change im ersten Versuch an. Schlägt eine Zustellung fehl, steht dort fehlgeschlagen, bei Fehler der Grund und bei Nächster Versuch der Zeitpunkt der Wiederholung.

knooing wiederholt eine Nachricht 1 Minute nach dem Fehlschlag, dann nach weiteren 5, 15 und 60 Minuten, danach jede Stunde. Nach dem 8. Versuch, gut vier Stunden nach dem ersten, gilt sie als aufgegeben.

Die Spalte Fehlerserie in der Liste zählt dagegen die Fehlschläge dieses Webhooks hintereinander, über alle Nachrichten hinweg. Nach 8 Fehlschlägen in Folge pausiert knooing den Webhook. Alle Personen mit der Befugnis Integrationen verwalten bekommen dazu eine Benachrichtigung in der Glocke und je nach eigener Einstellung per E-Mail.

Warum ein Protokoll? Fragt der Dienstleister, warum ihm ein Change fehlt, sehen Sie hier, ob und wann die Nachricht ankam.

Beispiel: Julia Beispiel legt einen Change für neue Firmware an den Etikettendruckern an. Kurz darauf steht Change angelegt mit zugestellt im Protokoll.

Ereignisse und ihre Namen in der Nachricht

Im Dialog stehen die Ereignisse auf Deutsch. In der Nachricht und beim Abruf stehen sie als technischer Name:

• Störungen: Störung angelegt = incident.created, Status geändert = incident.status_changed, Störung gelöst = incident.resolved, Störung geschlossen = incident.closed, Öffentliche Nachricht = incident.public_comment_added, Störung zugewiesen = incident.assigned.
• Service Requests: Service Request angelegt = service_request.created, Service Request: Status geändert = service_request.status_changed, Service Request zugewiesen = service_request.assigned, Service Request geschlossen = service_request.closed.
• Changes: Change angelegt = change.created, Change: Status geändert = change.status_changed, Change zugewiesen = change.assigned, Change geschlossen = change.closed.
• Freigabe und Umsetzung von Changes: Change: Freigabe erteilt = change.approved, Change: Freigabe abgelehnt = change.rejected, Change umgesetzt = change.implemented.
• Probleme: Problem angelegt = problem.created, Problem: Status geändert = problem.status_changed, Problem zugewiesen = problem.assigned, Problem geschlossen = problem.closed, Known Error angelegt = problem.known_error_created.

Change: Freigabe erteilt kommt bei mehrstufiger Freigabe für jede erteilte Stufe. Ein Known Error ist ein bekannter Fehler mit dokumentierter Umgehung, den jemand aus einem Problem abgeleitet hat.

Wenn etwas nicht klappt

• „Testzustellung an „…“ fehlgeschlagen.“ Unter der Meldung steht eine Zahl. Sie nennt die Antwort des Empfängers. Bei 401 oder 403 lehnt der Empfänger ab, meist weil das Secret dort fehlt oder falsch ist; lassen Sie es prüfen. Bei 404 stimmt die Adresse nicht. Ab 500 liegt beim Empfänger eine Störung vor. Steht keine Zahl da, ist der Empfänger nicht erreichbar, etwa wegen einer Firewall.
• „Geben Sie eine vollständige Adresse ein, die mit https:// beginnt.“ Die Adresse fehlt oder beginnt nicht mit https://. Tragen Sie die vollständige Adresse des Empfängers ein.
• „Ereignisse zu Service Requests, Changes und Problemen brauchen einen Schlüssel mit dem Lese-Scope der Vorgangsart. …“ Sie haben solche Ereignisse angehakt, aber keinen Schlüssel gewählt. „Lese-Scope“ heißt Lese-Berechtigung. Wählen Sie bei Schlüssel (optional) den Schlüssel des Fremdsystems, oder nehmen Sie die Haken weg.
• Die Auswahl bei Schlüssel (optional) ist leer. Es gibt noch keinen Schlüssel. Legen Sie ihn zuerst an, wie unter „Das brauchen Sie“ beschrieben.
• „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.
• Störungen kommen nicht an, Changes schon. Der Schalter Nur eigene Meldungen dieses Schlüssels ist an, und das Fremdsystem hat die Störungen nicht selbst gemeldet. Soll es alle Störungen bekommen, legen Sie einen Webhook mit ausgeschaltetem Schalter an.
• Das Secret ist verloren. Wählen Sie im Menü ⋯ Secret neu erzeugen und übergeben Sie das neue Secret. Bis es beim Empfänger hinterlegt ist, schlägt dort die Prüfung fehl.
• Change-Ereignisse kommen nicht an, Störungen schon. Dem gebundenen Schlüssel fehlt Changes lesen, oder die Person, die den Schlüssel angelegt hat, sieht diese Changes nicht. Die Berechtigungen eines bestehenden Schlüssels lassen sich nicht erweitern. Legen Sie einen Schlüssel mit der Berechtigung an und einen neuen Webhook dazu. Den alten löschen Sie im Menü ⋯ mit Löschen.
• Eine Zustellung steht auf aufgegeben. knooing schickt diese Nachricht nicht noch einmal. Das Ereignis bleibt 30 Tage gespeichert; mit einem Schlüssel mit Ereignisse abrufen kann das Fremdsystem es in dieser Zeit per Abruf holen.
• Der Webhook steht auf pausiert. Über der Liste steht der Grund, etwa „Nach 8 fehlgeschlagenen Zustellungen in Folge automatisch pausiert.“ Beheben Sie die Ursache beim Empfänger und wählen Sie im Menü ⋯ Fortsetzen. Was während der Pause anfällt, schickt knooing danach. Bleibt ein Webhook länger als 30 Tage pausiert, verfallen diese Nachrichten.
• Der Grund lautet „Der gebundene Schlüssel wurde widerrufen.“ Ein Webhook mit widerrufenem Schlüssel liefert nicht mehr, und Fortsetzen geht nicht. Legen Sie einen neuen Schlüssel und einen neuen Webhook an.
• Eine Nachricht kommt doppelt an. Das kann vorkommen, etwa wenn die Antwort des Empfängers verloren ging. Lassen Sie den Empfänger so einrichten, dass er jede X-Knooing-Delivery-Id nur einmal verarbeitet.
• Der Schlüssel läuft bald ab. Die Bindung des Webhooks lässt sich nicht ändern. Planen Sie rechtzeitig einen neuen Schlüssel und einen neuen Webhook ein; das Ablaufdatum steht in der Liste der Schlüssel bei Läuft ab.