Projektmanagement-Webhooks erklärt von Celoxis

Ein Celoxis-Webhook ist eine permanente Anweisung: Sobald in Celoxis eine bestimmte Aktivität stattfindet, z. B. die Erstellung eines Projekts, die Statusänderung einer Aufgabe oder die Genehmigung einer Ausgabe, sendet Celoxis diese Aktualisierung automatisch an eine von Ihnen festgelegte URL. Sie wählen die relevanten Aktivitäten aus, geben einen HTTPS-Endpunkt an, und Celoxis kümmert sich um den Rest. Niemand muss daran denken, die Nachricht weiterzuleiten, da dies das System automatisch im Moment der Änderung erledigt.

Das ist wichtig, weil die Alternative – das wiederholte Prüfen von Celoxis über die API, um festzustellen, ob sich etwas geändert hat – langsam ist, unnötig API-Aufrufe generiert und trotzdem eine Lücke zwischen der Änderung und der Benachrichtigung Ihres Teams hinterlässt. Ein Webhook schließt diese Lücke.

Jede Zustellung erfolgt als signierter JSON-POST-Request. Ihr Endpunkt empfängt das Ereignis, bestätigt dessen Herkunft von Celoxis und führt anschließend die entsprechende Aktion aus: Benachrichtigung eines Kanals, Erstellung eines CRM-Datensatzes, Start eines Abrechnungs-Workflows oder Übertragung der Änderung in ein Data Warehouse.

Jedes PMO stößt irgendwann an dieselbe Grenze: Das Projektsystem enthält zwar die korrekten Daten, aber diese müssen an fünf weitere Stellen übertragen werden: ein CRM-System, ein Slack-Kanal, ein Buchhaltungstool und ein BI-Dashboard. Keine dieser Stellen prüft Celoxis selbstständig. Jemand muss diese Lücke schließen, und lange Zeit war das entweder eine Person, die das manuell erledigte, oder ein Skript, das alle 60 Sekunden die API abfragte, um neue Daten zu erfassen.

Das Abfragen von Daten hat einen spezifischen, oft unterschätzten Kostenfaktor. Man verbringt viel Zeit mit API-Aufrufen, um nach Neuigkeiten zu fragen und erhält fast immer die Antwort „Nein“. Erst im entscheidenden Moment, wenn die Integration noch bis zu einer Minute hinterherhinkt, kommt die Antwort. Bei einem einzelnen Projekt ist das noch verkraftbar. Im gesamten Portfolio summiert es sich jedoch zu verschwendeter Infrastruktur und einem System, das sich immer einen Schritt hinterher anfühlt.

Ein zweites, spezifischeres Problem tritt vermehrt im Bereich der Projektmanagement-Software auf. Mehrere etablierte Plattformen haben ihre Webhook-Systeme nach dem Alles-oder-Nichts-Prinzip konzipiert: Nach der Anmeldung erhält man jedes Ereignis, jede Zellenbearbeitung, jeden Kommentar und jede noch so kleine Änderung – vermischt mit dem eigentlich gewünschten Signal. Teams entwickelten daher eigene Filter, nur um den Großteil der empfangenen Daten zu verwerfen. Einige Anbieter rüsten Systeme, die ursprünglich ohne Ereignisfilter ausgeliefert wurden, nun nachträglich mit dieser Funktion aus. Dies verdeutlicht, wie weit verbreitet diese Lücke ist.

Celoxis-Webhook-Ereignisse sind von Anfang an nach Elementtyp und Aktion kategorisiert. Sie können Ereignisse wie „Projekt hinzufügen“, „Aufgaben aktualisieren“ oder „Ausgaben löschen“ separat abonnieren. Dadurch entfällt die nachträgliche Anpassung vollständig. Weitere Informationen dazu finden Sie weiter unten.

Der Mechanismus ist bewusst einfach gehalten. Drei Schritte laufen jedes Mal ab:

1. In Celoxis findet eine Aktivität statt. Jemand erstellt ein Projekt, aktualisiert eine Aufgabe, erfasst Arbeitszeiten oder genehmigt eine Ausgabe.
2. Celoxis prüft Ihr Abonnement. Wenn Ihr Webhook so eingerichtet ist, dass er diese spezifische Aktivität überwacht, wird mit Schritt drei fortgefahren. Andernfalls geschieht nichts.
3. Celoxis sendet eine signierte Benachrichtigung per POST an Ihre Endpunkt-URL. Ihr System empfängt das Update nahezu in Echtzeit.

Wenn der Endpunkt nicht erreichbar ist oder einen Fehler zurückgibt, verwirft Celoxis das Ereignis nicht. Es versucht die Zustellung automatisch mit Backoff-Zeit erneut. Sobald der Zielort wieder erreichbar ist, können Sie die Zustellung auch manuell über die Admin-Oberfläche wiederholen. Eine Zustellung gilt als erfolgreich, wenn Ihr Endpunkt eine HTTP-2xx-Antwort zurückgibt.

Veranstaltungen, die Sie abonnieren können

Jeder Webhook überwacht „Hinzufügen“, „Aktualisieren“und „Löschen“ der von Ihnen ausgewählten Elementtypen. Sie müssen nicht alle Benachrichtigungen von Celoxis akzeptieren. Sie entscheiden, was für Sie relevant ist.

Einige konkrete Beispiele dafür, wie das in der Praxis aussieht:

• Es wird ein Projekt erstellt und ein CRM-Deal erscheint automatisch.
• Es wird eine Aufgabe hinzugefügt und der richtige Slack-Kanal wird benachrichtigt, ohne dass jemand eine Nachricht tippt.
• Eine Ausgabe wird genehmigt und die Buchhaltung wird in derselben Minute benachrichtigt, nicht erst bei der nächsten Stapelsynchronisierung.
• Die Arbeitszeit wird erfasst und ein Abrechnungsprozess wird automatisch gestartet.

Beginnen Sie mit ein oder zwei Ereignissen, nicht mit allen sechs. Mehr Ereignisse bedeuten mehr Benachrichtigungen, die auf Ihrem Endpunkt landen, und die meisten Integrationen benötigen nur einen kleinen Teil der Aktivität, um ihre Aufgabe gut zu erfüllen.

Wie die Nutzlast aussieht

Jede Zustellung erfolgt als JSON-Array. Celoxis kann mehrere übereinstimmende Ereignisse in einem POST-Request zusammenfassen, daher sollte Ihr Empfänger das Array durchlaufen, anstatt von einem einzelnen Objekt auszugehen.

Ein typisches Ereignis, bei dem eine Aufgabe geändert wird, sieht folgendermaßen aus:

Beispiel für eine Webhook-Nutzlast

JSON

[ { "type": "tasks.modified", "eventId": "<unique-event-id> ", "occurredAt": "<UTC ISO timestamp> ", "actor": { "value": 123, "text": "Alex Morgan" }, "resource": { "type": "tasks", "id": 456, "text": "Client-Kickoff-Präsentation vorbereiten", "url": "https://app.celoxis.com/..." }, "changes": [ { "field": "name", "label": "Name", "previous": { "value": "Entwurf der Kickoff-Präsentation", "text": "Entwurf der Kickoff-Präsentation" }, "current": { "value": "Client-Kickoff-Präsentation vorbereiten", "text": "Client-Kickoff-Präsentation vorbereiten" } } ] } ]

Einige Details, die bei der Implementierung Zeit sparen:

• Änderungen werden bei Aktualisierungsereignissen (*.modified) angezeigt. Hinzufüge- und Löschereignisse enthalten keine feldweise Differenzaufschlüsselung.
• Beim Löschen von Nutzdaten bleiben Ressourcentyp und ID erhalten. Name und URL werden weggelassen, da der Datensatz bereits gelöscht wurde.
• Die Genehmigung oder Ablehnung einer Ausgabe erfolgt als „expenses.modified“ und nicht als separates Ereignis.
• Verwenden Sie eventId und X-Celoxis-Delivery-Id für die Protokollierung und Idempotenz, damit ein Wiederholungsversuch keine doppelte Slack-Nachricht oder eine zweite Rechnungsposition erzeugt.

Ihr Endpunkt sollte schnell mit dem Statuscode 200, 201 oder 204 antworten. Die eigentliche Verarbeitung erfolgt erst nach der Bestätigung der Anfrage. Kann Celoxis keinen Statuscode 2xx empfangen, bleibt die Zustellung ausstehend und wird wiederholt.

Bevor Sie beginnen, benötigen Sie zwei Dinge: Administratorrechte mit der „Zugriff auf Webhooks“ und eine Endpunkt-URL, an die Celoxis Benachrichtigungen senden soll. Verwenden Sie in der Produktionsumgebung HTTPS.

1. Öffnen Sie die Seite „Webhooks“. Gehen Sie in Ihrem Profilmenü auf „Admin“, dann auf „Integrationen“ und anschließend auf „Webhooks“. Falls noch keine Webhooks vorhanden sind, ist die Liste leer.
2. Klicken Sie auf „+ Hinzufügen“. Dadurch wird das Formular „Webhook hinzufügen“ geöffnet.
3. Füllen Sie das Formular aus.
   • Name: etwas Aussagekräftiges, wie z. B. „Slack benachrichtigen, neue Aufgaben“, damit jeder, der Ihre Webhooks später überprüft, weiß, wozu sie dienen.
   • URL: Ihr Endpunkt, sorgfältig eingegeben
   • Geheimnis: Klicken Sie auf „Geheimnis generieren“. Celoxis verwendet dieses Geheimnis, um jede gesendete Benachrichtigung zu signieren. Ihr empfangendes System verwendet dasselbe Geheimnis, um die Echtheit der Anfrage zu bestätigen. Generierte Geheimnisse beginnen mit whsec_.
   • Aktiviert: Lassen Sie diese Option aktiviert, um sofort Benachrichtigungen zu erhalten.
   • Veranstaltungen: Wählen Sie mindestens eine Aktivität aus der obigen Liste aus.
4. Speichern. Ihr Webhook wird nun unter „Ihre Webhook-URLs“ angezeigt.

Von dort aus können Sie jederzeit den Namen, die URL, das Geheimnis oder die Ereignisauswahl bearbeiten, einen Webhook vorübergehend deaktivieren, ohne ihn zu löschen, oder ihn endgültig löschen, wenn Sie sicher sind, dass Sie ihn nicht mehr benötigen.

Eine Einschränkung, die Sie bei Ihrer Planung berücksichtigen sollten: Celoxis erlaubt maximal fünf Webhooks pro Unternehmen. Überlegen Sie sich Ihre Integrationsanforderungen genau, bevor Sie die Webhooks einzeln erstellen. Wenn mehrere nachgelagerte Systeme auf dieselben Ereignisse reagieren sollen, richten Sie einen Webhook an einen internen Router oder eine iPaaS-Plattform und verteilen Sie die Webhooks von dort aus, anstatt für jedes Ziel einen eigenen Webhook zu verwenden.

Wenn Sie die Endpunkt-URL aktualisieren, werden ausstehende und fehlgeschlagene Zustellungen an die neue Adresse umgeleitet. Bereits zugestellte Ereignisse bleiben unverändert.

Dies ist der Abschnitt, der für einen CTO, der prüft, ob Webhooks sicher an einen externen Endpunkt weitergegeben werden können, am wichtigsten sein dürfte, und es lohnt sich, ihn richtig zu verstehen, anstatt ihn nur zu überfliegen.

Jede Anfrage, die Celoxis sendet, enthält neben dem JSON-Body drei Header:

Wie die Signatur erzeugt wird

Celoxis verknüpft den Zeitstempel und den Rohnachrichtentext mit einem Punkt und führt dann diesen kombinierten Text mithilfe Ihres Geheimnisses durch HMAC-SHA256:

HMAC-SHA256(secret, “{timestamp}.{rawBody}”)

Das Ergebnis wird als Wert v1= in X-Celoxis-Signature gesendet. Dasselbe Geheimnis und dieselbe Nachricht erzeugen immer dieselbe Signatur, aber es gibt keine Möglichkeit, die Signatur wieder in das Geheimnis selbst umzuwandeln.

So können Sie es auf Ihrer Seite überprüfen

1. Verwenden Sie die Nachricht exakt so, wie sie ankommt. Formatieren oder erstellen Sie sie nicht vorher neu, selbst eine kleine Änderung kann die Übereinstimmung beeinträchtigen.
2. Extrahieren Sie den Zeitstempel und die Signatur aus den Anfrageheadern.
3. Erstellen Sie die Signatur selbst mithilfe von HMAC-SHA256 und Ihrer Kopie des Geheimnisses neu.
4. Vergleiche die beiden Angaben. Stimmen sie überein, ist die Anfrage echt und du kannst sie annehmen. Stimmen sie nicht überein, lehne sie ab.

Als zusätzliche Maßnahme empfiehlt es sich, Anfragen abzulehnen, deren Zeitstempel älter als einige Minuten ist (fünf Minuten sind ein sinnvoller Standardwert), damit abgefangene Nachrichten nicht später erneut gesendet werden können. Celoxis schreibt dies zwar nicht zwingend vor, es ist aber eine bewährte Vorgehensweise.

Hier ist ein Node.js-Skizze derselben Überprüfung:

Überprüfen einer Celoxis-Webhook-Signatur

Node.js

const crypto = require("crypto"); function verifyCeloxisWebhook({ rawBody, timestamp, signatureHeader, secret }) { const expected = crypto .createHmac("sha256", secret) .update(`${timestamp}.${rawBody}`) .digest("hex"); const actual = new URLSearchParams( signatureHeader.replace(/,/g, "&") ).get("v1"); const ageSeconds = Math.abs( Date.now() / 1000 - Number(timestamp) ); if (!actual || ageSeconds > 300) return false; return crypto.timingSafeEqual( Buffer.from(expected), Buffer.from(actual) ); }

Halten Sie das Geheimnis geheim. Jeder, der es kennt, kann gefälschte Anfragen erstellen, die legitim aussehen. Wenn Sie das Geheimnis neu generieren, aktualisieren Sie es gleichzeitig auf der Empfängerseite, da das alte sonst nicht mehr funktioniert und jede Anfrage bei der Verifizierung fehlschlägt. Beide Seiten müssen immer exakt übereinstimmen.

Webhooks sind auf Administratoren beschränkt, und selbst dann benötigt eine Rolle die spezifische „Zugriff auf Webhooks“, bevor sie die Webhooks-Seite überhaupt öffnen kann. Andernfalls erhalten Benutzer die Meldung „Zugriff verweigert“.

Diese Funktion ist an einen bestimmten Tarif gebunden. Wenn Webhooks in Ihrem Tarif nicht aktiviert ist, wird das Menü nicht angezeigt. Wenden Sie sich an Ihren Celoxis-Administrator oder den Celoxis-Support, falls Sie das Menü erwartet haben, es aber nicht sehen.

Ein Administrator erteilt die Berechtigung über das Hauptmenü, dann Admin, dann Einstellungen, dann Zugriffskontrolleunter der Registerkarte Unternehmen, indem er den Zugriff auf Webhooks für die entsprechende Rolle auf Gewähren setzt.

Das ist wichtiger, als es zunächst scheinen mag. Webhooks übertragen vertrauliche Daten und stellen eine Live-Verbindung zu externen Systemen her. Eine fehlerhafte oder unachtsame Integration kann schnell zu Datenlecks oder Störungen führen. Celoxis empfiehlt daher ausdrücklich: Clientbenutzern keinen Zugriff auf Webhooks gewähren. Dies ist eine sinnvolle Standardeinstellung für jede Organisation, die sensible Projekt- oder Finanzdaten interner und externer Stakeholder verwaltet.

Die Einrichtung eines Webhooks ist nicht das Ende der Arbeit. Genauso wichtig ist es zu wissen, ob er tatsächlich funktioniert, und Celoxis bietet hierfür zwei separate Ansichten.

„Letzte Zustellungen“auf der Detailseite des Webhooks zeigt die aktuellsten ausstehenden und fehlgeschlagenen Versuche an. Sie dient dazu, Probleme schnell zu erkennen, und ist nicht als vollständige Liste gedacht. Wenn diese Liste leer ist, bedeutet das nicht, dass keine Sendungen gesendet wurden. Es bedeutet lediglich, dass derzeit keine ausstehenden oder fehlgeschlagenen Sendungen vorhanden sind. Erfolgreiche Zustellungen werden an anderer Stelle gespeichert.

„Alle anzeigen“ öffnet die vollständige Zustellungshistorie in einem Slider-Panel, einschließlich aller Sendungen mit dem Status „Zugestellt“, „Ausstehend“ oder „Fehlgeschlagen“. Ein Klick auf das Augensymbol in einer beliebigen Zeile öffnet die vollständigen Zustellungsdetails im JSON-Format, darunter Status, Anzahl der Versuche, HTTP-Antwortcode und die exakte Nutzlast, die Celoxis gesendet hat.

Der Lieferstatus lässt sich in drei Zustände unterteilen:

Beheben Sie bei ausstehenden oder fehlgeschlagenen Vorgängen zuerst die zugrundeliegende Ursache (z. B. eine falsche URL oder ein nicht erreichbares Empfangssystem) und verwenden Sie anschließend die Funktion „Wiederholen“. Erfolgreiche Zustellungen können nicht wiederholt werden, da sie bereits zugestellt wurden.

Diese In-Product-Ansicht ist der entscheidende Unterschied: Sie entdecken einen Integrationsfehler entweder selbst oder erfahren erst zwei Wochen später von einem Kunden davon.

Die meisten Webhook-Probleme lassen sich auf wenige Ursachen zurückführen. Hier erfahren Sie, was häufig schiefgeht und wie Sie das Problem beheben können.

Die am häufigsten auftretenden Anwendungsfälle folgen einem Muster: Etwas ändert sich in Celoxis, und ein anderes System muss ohne menschliches Eingreifen reagieren.

• CRM-Synchronisierung: Ein neues Projekt löst automatisch einen entsprechenden Deal oder Datensatz aus, sodass Vertrieb und Lieferung ohne manuelle Neueingabe aufeinander abgestimmt bleiben.
• Teambenachrichtigungen: Aufgabenerstellung oder Statusänderungen erreichen Slack oder Teams in dem Moment, in dem sie erfolgen, anstatt erst zwei Tage später in einer Statusbesprechung zur Sprache zu kommen.
• Automatisierte Abrechnung: Erfasste Arbeitszeiten oder genehmigte Ausgaben fließen direkt in die Rechnungsstellungs- oder Lohnabrechnungsprozesse ein.
• BI und Reporting: Projekt- und Aufgabendaten fließen kontinuierlich in ein Data Warehouse oder Dashboard, anstatt sich auf einen nächtlichen Batch-Export zu verlassen, der immer etwas veraltet ist.
• Toolübergreifende Workflows: Celoxis wird mit Jira, Salesforce, ServiceNow oder einem internen System verbunden, das speziell auf die Arbeitsweise Ihrer Organisation zugeschnitten ist.

Keine dieser Lösungen erfordert benutzerdefinierte Abfrageskripte oder geplante Jobs zur Überprüfung auf Änderungen. Sie benötigen lediglich einen Webhook, der auf die richtigen Ereignisse beschränkt ist und auf den richtigen Endpunkt verweist.

Wenn Sie Plattformen vergleichen und nicht einfach das übernehmen, was Ihr PM-Tool gerade anbietet, entscheiden einige wenige Fragen darüber, ob ein Webhook-System im Produktivbetrieb funktioniert oder ob es nach sechs Monaten zur Wartungsbelastung wird.

1. Kann man bestimmte Ereignisse abonnieren oder nur alle gleichzeitig? Breite, ungefilterte Ereignisströme bedeuten, dass Sie Ihre eigene Filterlogik nachgelagert implementieren müssen, was zusätzlichen Wartungsaufwand und eine größere Angriffsfläche für Fehler bedeutet.
2. Wird jede Anfrage signiert und die Verifizierung dokumentiert? Ein Webhook ohne Signaturverifizierung ist ein Sicherheitsrisiko. Fragen Sie konkret nach dem Signiervorgang, nicht nur nach dessen Existenz. Sie benötigen HMAC, einen Zeitstempel und eine Zustellungs-ID, keinen gemeinsam genutzten Header, den jeder kopieren kann.
3. Können Sie die Lieferhistorie einsehen oder tappen Sie im Dunkeln? Wenn ein Webhook zwei Wochen lang unbemerkt ausfällt, benötigen Sie eine Möglichkeit, dies herauszufinden, und zwar nicht nur durch die Aussage „Ein Kunde erwähnt, dass seine Integration anscheinend nicht funktioniert“.
4. Ist der Zugriff auf die Erstellung und Verwaltung von Webhooks tatsächlich eingeschränkt? Jeder, der einen Webhook erstellen kann, kann sensible Projektdaten an externe Stellen weiterleiten. Dies sollte durch eine spezifische Berechtigung geschützt sein und nicht standardmäßig über allgemeine Administratorrechte erfolgen.
5. Wo liegt die praktische Grenze? Eine feste Obergrenze für Webhooks pro Konto ist in Ordnung, aber man muss wissen, dass diese Grenze existiert, bevor man fünf verschiedene Integrationen auf der Annahme aufbaut, dass man eine sechste erstellen kann.

Celoxis beantwortet diese fünf Fragen in der Admin-Benutzeroberfläche: Ereignisfilter, HMAC-SHA256-Signierung mit Zeitstempel und Zustellungs-ID, eine integrierte Zustellungshistorie mit JSON-Payload-Viewer, eine dedizierte Zugriffsberechtigung für Webhooks und eine veröffentlichte Obergrenze von fünf Webhooks pro Unternehmen.

Alle Plattformen dieser Kategorie bieten Webhooks in irgendeiner Form. Sie unterscheiden sich hinsichtlich Granularität, Sicherheitsvorgaben und Transparenz nach der Inbetriebnahme. Dieser Vergleich basiert auf der jeweils veröffentlichten Entwicklerdokumentation der Anbieter (Stand: [Datum einfügen]).

Einige Punkte fallen hier besonders auf. Celoxis und Wrike unterstützen beide die Ereignisfilterung auf Konto- oder unternehmensweiter Ebene, ohne dass ein separater Webhook pro Board erforderlich ist, wie es monday.com aktuell der Fall ist. Celoxis gehört außerdem zu den wenigen Anbietern in dieser Gruppe, bei denen Signaturprüfung, Zustellungsüberwachung und Berechtigungsverwaltung direkt in die Administrationsoberfläche integriert sind und keine API-Aufrufe oder Drittanbieter-Tools zur Überprüfung benötigen. Asana und monday.com setzen eher auf Entwickler-Tools als auf eine integrierte Ansicht. Dies funktioniert zwar gut für ein dediziertes Entwicklerteam, führt aber zu Problemen, wenn das PMO Einblick benötigt, ohne für jede Prüfung die IT-Abteilung einbeziehen zu müssen.

Keine der hier vorgestellten Plattformen ist in jeder Hinsicht objektiv die „beste“. Wenn Ihr Team API-orientiert arbeitet und bereits über starke technische Unterstützung verfügt, ist das Modell von Asana praktikabel. Benötigen Sie hingegen umfassende, native Transparenz ohne den Aufbau einer separaten Überwachungsschicht, bietet die integrierte Bereitstellungsansicht von Celoxis den direkteren Weg.

Webhooks lösen ein spezifisches, wiederkehrendes Problem: die Synchronisierung von Systemen ohne manuelle Eingriffe oder langsame Abfrageskripte. Celoxis-Webhooks bieten Ihnen von Anfang an die volle Kontrolle über Ereignisse, einen dokumentierten HMAC-SHA256-Verifizierungsprozess und eine direkt in die Administrationsoberfläche integrierte Zustellungsüberwachung – ganz ohne separate Integration.

Ob das die richtige Lösung ist, hängt davon ab, womit Sie Celoxis verbinden, wie viel technische Unterstützung Ihnen für den Aufbau und die Wartung der Empfangsseite zur Verfügung steht und wie viele Integrationen Sie realistischerweise gleichzeitig ausführen müssen.

Wenn Sie dies mit Ihrem aktuellen Stack vergleichen, dauern die oben genannten Einrichtungsschritte nur wenige Minuten für einen umfassenden Test, was in der Regel ausreicht, um festzustellen, ob es passt.

Die Einrichtung Ihres ersten Webhooks dauert etwa zehn Minuten, sofern Ihr Endpunkt einsatzbereit ist. So können Sie die tatsächlichen Nutzdaten einsehen, bevor Sie eine umfangreichere Integration vornehmen. Wenn Sie den gesamten Ablauf lieber anhand Ihrer eigenen Projektdaten durchgehen möchten, buchen Sie eine Celoxis-Demo oder starten Sie eine kostenlose Testphase.