APIs und Webhooks in Workflows

Über eine API kann ein Workflow Daten abrufen oder eine Aktion in einem anderen System anfordern. Ein Webhook meldet ein Ereignis, das ein Dienst an einen Empfangsendpunkt zustellt. Für einen brauchbaren Ablauf müssen Auslöser, Datenprüfung und gewünschtes Ergebnis feststehen. Eine angenommene Nachricht belegt noch keinen abgeschlossenen Geschäftsvorgang.

Die Format- und Protokollgrundlagen sind genormt: RFC 8259 beschreibt JSON als leichtgewichtiges, textbasiertes und sprachunabhängiges Datenaustauschformat. RFC 9110 vom Juni 2022 beschreibt die Semantik von HTTP als IETF-Standard.

Den Austausch vom Ergebnis her planen

Angenommen, eine interne Anwendung soll eine genehmigte Materialanforderung an ein anderes System übergeben. Legen Sie zuerst fest, welcher Datensatz dort entstehen oder geändert werden soll und woran die erfolgreiche Übernahme zu erkennen ist.

Ein erfolgreicher HTTP-Status beschreibt zunächst nur das Ergebnis der betreffenden Anfrage. Ob der richtige Vorgang im Zielsystem den gewünschten Zustand erreicht hat, hängt von der dokumentierten Bedeutung der API-Operation ab und ist gesondert zu prüfen.

Eine Änderungsabfrage mit Zustandstoken führen

Eine Delta-Abfrage arbeitet als Pull-Verfahren: Die Anwendung fordert mit einer GET-Anfrage die Änderungen einer Ressourcensammlung an. Die Antwort enthält den Zustand und ein Zustandstoken. Verweist sie über @odata.nextLink auf weitere Seiten, sind diese abzurufen. Liefert sie @odata.deltaLink, sind für die laufende Sitzung keine weiteren Daten offen; spätere Anfragen nutzen diesen Link, und eine Seite enthält nie beide Verweise.

Microsoft Graph nennt die Delta-Abfrage auch Änderungsnachverfolgung. Die erste Abfrage enthält die aktuell vorhandenen Ressourcen; spätere Anfragen mit dem Delta-Link fragen Änderungen ab. Nicht überall steht die Funktion bereit: In Microsoft Entra External ID in externen Mandanten und in Azure AD B2C-Mandanten wird sie nicht unterstützt.

Vorteile und Risiken von Delta-Abfragen

Webhook oder regelmäßige Abfrage wählen

Ein Webhook passt, wenn der Anbieter das benötigte Ereignis bereitstellt und der Workflow Zustellungen zuverlässig empfangen kann. Bei einer regelmäßigen Abfrage startet der eigene Workflow den Abruf nach einem Zeitplan. Das kann passen, wenn kein geeignetes Ereignis angeboten wird oder eingehende Zustellungen für den vorgesehenen Aufbau nicht praktikabel sind.

Ob eine Änderungsbenachrichtigung als Anlass für eine anschließende Änderungsabfrage dienen kann, hängt von der jeweiligen Integration ab.

Empfangsendpunkt und Abonnement vorbereiten

Microsoft Graph verlangt für Webhooks einen öffentlich erreichbaren, über eine URL adressierbaren Endpunkt mit HTTPS. Ist er nicht öffentlich erreichbar, werden keine Benachrichtigungen zugestellt.

Für die Überwachung wird ein Abonnement auf die Ressource angelegt; solange es gültig ist, sendet der Dienst bei jeder erkannten Änderung eine Benachrichtigung. Der Endpunkt muss authentifiziert bleiben, indem das Abonnement erneuert oder auf Lebenszyklusbenachrichtigungen geantwortet wird.

GitHub rät davon ab, eigene API-Schlüssel oder andere Anmeldedaten in die Payload-URL aufzunehmen. Zur Prüfung dient stattdessen ein Webhook-Secret aus einer Zufallszeichenfolge hoher Entropie, das sicher gespeichert wird.

Der Server soll HTTPS mit aktivierter SSL-Prüfung verwenden und Zustellungen über eine IP-Allowlist auf die von GitHub verwendeten Adressen beschränken; diese Liste veröffentlicht GitHub über die REST-API und ändert sie gelegentlich.

Schritte zur sicheren Nutzung von Webhooks

Eingehende und ausgehende Daten prüfen

Ein Webhook-Endpunkt sollte nur vorgesehene Ereignistypen und Aktionen verarbeiten. Prüfen Sie die Nachricht mit dem Verfahren des jeweiligen Anbieters; GitHub empfiehlt beispielsweise ein Webhook-Secret und die Prüfung der Signatur. Eine öffentlich erreichbare URL allein weist den Absender nicht nach.

Auch eine API-Antwort braucht vor der Feldzuordnung eine Prüfung: Welcher Status wurde geliefert, gibt es einen Antwortkörper, und entsprechen dessen Struktur und Werte der dokumentierten Operation? Ein fehlendes Feld, null, eine leere Zeichenfolge und die Zahl 0 können fachlich Unterschiedliches bedeuten. Prüfen Sie anhand der Dokumentation, ob die jeweilige Operation einen Antwortkörper vorsieht.

Bei GitHub lässt sich der Ereignistyp über den Anfrage-Header X-GitHub-Event bestimmen, die Aktion über den Schlüssel action auf oberster Ebene der Nutzlast. Da GitHub laufend neue Ereignistypen und Aktionen ergänzt, gehört diese Prüfung vor jede Verarbeitung. Empfohlen ist zudem, nur die tatsächlich benötigten Ereignisse zu abonnieren.

Prüfungen vor der Verarbeitung eingehender Daten

Empfang und Verarbeitung trennen

Für Webhook-Antworten gelten die Vorgaben des jeweiligen Anbieters. GitHub erwartet eine 2xx-Antwort innerhalb von zehn Sekunden; Microsoft Graph betrachtet eine Änderungsbenachrichtigung als zugestellt, wenn der Endpunkt innerhalb von drei Sekunden mit 2xx antwortet.

Für längere Verarbeitung empfiehlt Microsoft Graph, die geprüfte Benachrichtigung zunächst verlässlich in einer Warteschlange zu speichern und dann mit 202 Accepted zu antworten. Diese Fristen und Verfahren sind nicht auf andere Dienste übertragbar.

Legen Sie fest, wie Zustellung, Annahme, spätere Verarbeitung und Zielergebnis voneinander unterschieden werden. Welche Rückmeldungen und Nachholwege gelten, hängt von der jeweiligen Quelle ab.

Zeitlimits für Webhook-Antworten (Anbieterabhängige Anforderungen)

Einen Fall vor dem Einsatz durchgehen

Verwenden Sie unkritische Beispieldaten für ein erwartetes Ereignis, ein nicht relevantes Ereignis, eine fehlende Pflichtangabe und eine erneute Zustellung. Legen Sie für jeden Fall fest, was am Empfangsendpunkt und im Zielsystem erkennbar sein soll.