Microsoft Graph Webhooks einfach erklärt

Wer mit Microsoft 365 Anwendungen baut, steht früher oder später vor derselben Frage: Wie erfährt meine App, dass sich etwas geändert hat? Der naheliegende Weg ist, Microsoft Graph immer wieder zu fragen. Das funktioniert, ist aber ineffizient und liefert trotzdem keine Echtzeitdaten.

Microsoft Graph Webhooks, offiziell Änderungsbenachrichtigungen, drehen das Prinzip um: Nicht Ihre App fragt ständig nach, sondern Graph meldet sich, sobald etwas passiert. Dieser Artikel erklärt, wie das funktioniert, worauf Sie bei Einrichtung und Betrieb achten müssen und wie Sie Webhooks mit Delta-Abfragen zuverlässig machen.

Das Polling-Problem: Warum ständiges Nachfragen schadet

Stellen Sie sich vor, Sie erwarten einen wichtigen Brief und gehen den ganzen Tag alle zehn Minuten zum Briefkasten. Meistens ist er leer. Genau so arbeitet Polling: Die App fragt Microsoft Graph „Gibt es neue Benutzer?“, Graph antwortet „Nein“, die App wartet kurz und fragt erneut.

Verschwendete Anfragen und Drosselung

Fragt Ihre App alle fünf Minuten nach Benutzeränderungen, sind das zwölf Anfragen pro Stunde – und zwar nur für eine einzige Ressource. Kommen Gruppen, Dateien, Nachrichten und Kalenderereignisse hinzu, summieren sich pro Tag tausende unnötige Aufrufe, von denen die meisten keine einzige Änderung zurückliefern. Wenn tausende Apps gleichzeitig so vorgehen, entsteht enormer Lärm.

Microsoft begrenzt deshalb die Anzahl der Aufrufe pro App. Wer zu aggressiv abfragt, wird gedrosselt, von manchen Entwicklern „Graph Jail“ genannt. Dann wird alles langsamer, und auch legitime Anfragen stauen sich.

Trotzdem keine Echtzeit

Selbst bei einer Abfrage alle fünf Minuten bekommen Sie keine Echtzeitdaten. Ändert sich eine Minute nach der letzten Abfrage etwas, erfahren Sie erst vier Minuten später davon. Sie verbrauchen also Ressourcen und verpassen trotzdem das Zeitfenster.

Was sind Graph Webhooks? Änderungsbenachrichtigungen erklärt

Ein Webhook ist eine HTTP-Anforderung, die automatisch gesendet wird, wenn etwas passiert. Sie fragen nicht danach, der Server schickt sie Ihnen. Ein passendes Bild ist die Türklingel: Sie stehen nicht draußen und prüfen alle paar Minuten die Tür, sondern warten, bis es klingelt.

Webhooks werden manchmal „umgekehrte APIs“ genannt. Bei einer normalen API stellt Ihre App eine Anfrage und der Server antwortet. Bei einem Webhook sendet der Server die Anfrage an Ihre App. Microsoft Graph nutzt dieses Prinzip unter dem Namen Änderungsbenachrichtigungen. Gemeint ist dasselbe.

Ändert sich etwas in Microsoft 365, schickt Graph eine HTTP-POST-Nachricht an eine URL, die Sie angegeben haben. Auslöser können sein:

• ein neuer Benutzer in Ihrem Mandanten
• eine aktualisierte Datei in SharePoint
• eine gesendete Nachricht in Teams
• ein geändertes Kalenderereignis
• ein neues Mitglied in einer Gruppe

Zwei Anwendungsfälle

Angenommen, ein Unternehmen betreibt ein Zeiterfassungssystem und möchte für neue Mitarbeiter automatisch ein Konto anlegen. Mit Webhooks abonnieren Sie die Benutzererstellung. Tritt jemand bei, erhält Ihre App eine Benachrichtigung, validiert sie und erstellt das Konto innerhalb von Sekunden.

Ein zweites Beispiel ist eine SharePoint-Dokumentbibliothek, in die Belege hochgeladen werden. Statt die Bibliothek ständig abzufragen, werden Sie benachrichtigt, sobald eine Datei hinzukommt. Ihre App ruft die Datei ab, prüft, ob es ein Beleg ist, und verarbeitet sie automatisch.

So funktionieren Microsoft Graph Webhooks: Abonnement, Benachrichtigung, Endpunkt

Der Ablauf beruht auf drei Bausteinen:

1. Abonnement: Ihre Anforderung an Graph, über bestimmte Änderungen informiert zu werden. Graph speichert sie und überwacht die Ressource fortan in Ihrem Auftrag.
2. Benachrichtigung: Die eigentliche HTTP-POST-Nachricht an Ihre URL. Sie enthält Details zur Änderung, etwa welche Ressource betroffen ist, welche Art von Änderung stattfand und wann.
3. Endpunkt: Eine URL auf Ihrem Server, die diese POST-Anfragen entgegennimmt.

Ihr Endpunkt braucht keine komplexe Logik. Er nimmt die Benachrichtigung an, bestätigt sie und gibt sie zur Verarbeitung weiter. Er muss öffentlich erreichbar sein, HTTPS sprechen und schnell antworten. Beim Polling wären es hunderte GET-Anfragen, die meist mit „Nein“ beantwortet werden. Mit Webhooks genügt eine Nachricht, wenn wirklich etwas passiert.

Abonnement erstellen und den Validierungshandshake bestehen

Ein Abonnement legen Sie an, indem Sie eine HTTP-POST-Anforderung an den Abonnement-Endpunkt von Microsoft Graph senden. Im Anforderungstext sind vier Angaben nötig:

• Benachrichtigungs-URL: Adresse Ihres Endpunkts. Sie muss HTTPS verwenden und öffentlich erreichbar sein, da Graph sie über das Internet aufruft.
• Ressource: Was überwacht werden soll, zum Beispiel Benutzer oder Nachrichten im Posteingang.
• Änderungstyp: erstellt, aktualisiert, gelöscht oder eine Kombination. Wer nur neue Benutzer braucht, wählt „erstellt“.
• Ablaufdatum und -uhrzeit: Danach sendet Graph keine Benachrichtigungen mehr.

Optional, aber wichtig ist der Client-Status: eine geheime Zeichenfolge, die Sie selbst festlegen. Graph fügt sie in jede Benachrichtigung ein. So können Sie später prüfen, ob eine Nachricht wirklich zu Ihrem Abonnement gehört.

Der Validierungshandshake

Bevor das Abonnement live geht, prüft Graph, ob Ihr Endpunkt echt und empfangsbereit ist. Dazu sendet Graph sofort nach Ihrer Anfrage einen Testaufruf an die Benachrichtigungs-URL. Er enthält den Abfrageparameter „validationToken“, eine zufällige Zeichenfolge. Ihr Endpunkt muss dieses Token innerhalb von 10 Sekunden als reinen Text zurücksenden.

Hier stolpern viele Entwickler:

• Das Token muss als einfacher Text zurückkommen, nicht als JSON und nicht als HTML.
• Der Content-Type-Header muss text/plain lauten.
• Wird die Antwort in JSON verpackt oder anders codiert, schlägt die Validierung fehl und das Abonnement wird nicht erstellt.
• Der Validierungsdienst von Graph unterstützt TLS 1.3 nicht zuverlässig und verhandelt TLS 1.2. Akzeptiert Ihr Endpunkt ausschließlich TLS 1.3, scheitert der Handshake, bevor Ihr Anwendungscode überhaupt läuft. Stellen Sie sicher, dass TLS 1.2 zumindest für diesen Schritt unterstützt wird.

Der Handshake findet nur einmal pro Abonnement statt. Danach vertraut Graph Ihrem Endpunkt für die gesamte Laufzeit.

Benachrichtigungen verarbeiten: Sicherheit, Tempo und Drosselung

Sobald das Abonnement aktiv ist, sendet Graph bei jeder Änderung eine POST-Nachricht mit einem JSON-Objekt. Es enthält die geänderte Ressource, die Art der Änderung (erstellt, aktualisiert oder gelöscht), einen Zeitstempel und den von Ihnen festgelegten Client-Status.

Erst prüfen, dann verarbeiten

Das Erste, was Ihr Endpunkt tun sollte: den Client-Status in der Benachrichtigung mit dem gespeicherten Geheimnis vergleichen. Stimmt er nicht überein, verwerfen Sie die Nachricht sofort. Ihr Endpunkt liegt im öffentlichen Internet, jeder, der die URL kennt, könnte eine Nachricht schicken. Ohne diese Prüfung können Sie echte und gefälschte Benachrichtigungen nicht unterscheiden.

Schnell antworten

Graph erwartet innerhalb von drei Sekunden eine HTTP-Antwort der Stufe 200. Dauert das zu oft zu lange, greift eine Drosselung:

• Überschreiten mehr als 10 % der Antworten innerhalb von 10 Minuten das Zeitfenster von drei Sekunden, markiert Graph den Endpunkt als langsam. Neue Benachrichtigungen werden dann um 10 Minuten verzögert, die Echtzeit geht verloren.
• Überschreiten mehr als 15 % der Antworten 10 Sekunden, gilt der Endpunkt als „verworfen“. Benachrichtigungen werden dann für 10 Minuten vollständig verworfen, und verworfene Benachrichtigungen lassen sich nicht wiederherstellen.

Die bewährte Methode lautet daher: Benachrichtigung sofort quittieren und asynchron verarbeiten. Der Endpunkt prüft den Client-Status, nimmt die Nachricht an und gibt so schnell wie möglich eine Antwort der Stufe 200 zurück, etwa 202 Accepted. Danach landet die Benachrichtigung in einer Warteschlange, etwa einer Azure-Warteschlange, einem Service Bus oder sogar einer einfachen Datenbanktabelle. Ein Hintergrund-Worker erledigt die eigentliche Arbeit.

Erreichbarkeit

Der Endpunkt muss ausnahmslos HTTPS verwenden und öffentlich zugänglich sein. Hinter einer Firewall oder einem VPN kann Graph ihn nicht erreichen. Für die Entwicklung lässt sich ein öffentlicher Tunnel zum lokalen Rechner einrichten. In der Produktion muss der Endpunkt dagegen an einem Ort liegen, an dem Graph ihn findet.

Abonnements verlängern und mit Delta-Abfragen absichern

Abonnements laufen ab. Die maximale Dauer hängt von der Ressource ab: Für Benutzer und Gruppen beträgt sie etwa drei Tage, für Laufwerkselemente in SharePoint oder OneDrive kann sie bis zu 30 Tage betragen. Prüfen Sie die Dokumentation für jeden Ressourcentyp. Nach Ablauf sendet Graph keine Benachrichtigungen mehr, und das fällt oft erst auf, wenn man sich wundert, warum nichts mehr passiert.

Verlängerung und Lebenszyklusbenachrichtigungen

Zum Verlängern senden Sie mit der Abonnement-ID eine PATCH-Anforderung an den Abonnement-Endpunkt und setzen ein neues Ablaufdatum. Das geht beliebig oft, solange es vor dem aktuellen Ablauf geschieht.

Unterstützung bieten Lebenszyklusbenachrichtigungen. Beim Erstellen des Abonnements können Sie dafür eine eigene URL angeben. Graph meldet sich dort, wenn das Abonnement bald abläuft, wenn ein Zugriffstoken bald abläuft oder wenn sich Berechtigungen Ihrer App ändern. Sie müssen den Ablauf also nicht erraten.

Delta-Abfrage als Sicherheitsnetz

Was aber, wenn Ihr Endpunkt zeitweise ausfällt oder Benachrichtigungen verworfen werden? Hier hilft die Delta-Abfrage, ein eigenes Feature von Microsoft Graph. Sie beantwortet die Frage: „Was hat sich seit meiner letzten Prüfung geändert?“

1. Der erste Aufruf der Delta-Abfrage, etwa für Benutzer, liefert alle Benutzer und zusätzlich einen Delta-Link.
2. Diesen Link speichern Sie.
3. Beim nächsten Mal nutzen Sie den Delta-Link und erhalten nur noch neue, aktualisierte und gelöschte Benutzer.

Das ist, als würden Sie eine Liste mit Neuigkeiten lesen, statt jedes Mal die ganze Enzyklopädie. Die Kombination ist das empfohlene Muster: Webhooks sagen, dass sich etwas geändert hat, die Delta-Abfrage sagt, was sich geändert hat. Webhooks sorgen für Geschwindigkeit, Delta-Abfragen für Zuverlässigkeit.

Typischer Ablauf:

1. Webhook-Abonnement für Benutzeränderungen einrichten.
2. Eine erste Delta-Abfrage ausführen, Basisstatus abrufen und den Delta-Link speichern.
3. Bei einer eingehenden Benachrichtigung die Delta-Abfrage mit dem gespeicherten Link ausführen.
4. Änderung verarbeiten und den neuen Delta-Link aus der Antwort speichern.
5. Bei verpassten Benachrichtigungen oder abgelaufenem Abonnement die Delta-Abfrage einfach erneut ausführen.

Praxisbeispiel: Onboarding eines neuen Mitarbeiters

Die Personalabteilung legt in der Microsoft Entra ID ein Konto für einen neuen Mitarbeiter an. Weil Sie ein Webhook-Abonnement für Benutzeränderungen eingerichtet haben, bemerkt Graph das sofort und sendet einen POST an Ihren Endpunkt.

Der Endpunkt prüft den Client-Status und antwortet innerhalb von drei Sekunden mit 202 Accepted. Der Hintergrund-Worker übernimmt die Benachrichtigung. Da sie nicht alle Details enthält, führt er mit dem gespeicherten Delta-Link eine Delta-Abfrage aus und erhält die vollständigen Informationen: Name, E-Mail-Adresse, Abteilung, Stellenbezeichnung und Vorgesetzte. Damit erstellt er ein Konto im externen Zeiterfassungssystem, sendet eine Willkommens-E-Mail und trägt den Mitarbeiter in die passenden Verteilerlisten ein.

All das geschieht wenige Sekunden nach der Kontoerstellung, ohne Polling und ohne manuelle Schritte. Ohne Webhooks wären es hunderte Abfragen pro Tag, und es könnte trotzdem mehrere Minuten dauern, bis der neue Benutzer auffällt.

Häufige Fehler und Stolpersteine

• Falsches Antwortformat bei der Validierung: Das Token muss als text/plain zurückgegeben werden, nicht als JSON oder HTML.
• Nur TLS 1.3 aktiviert: Der Handshake scheitert, weil Graph TLS 1.2 verhandelt.
• Endpunkt nicht öffentlich oder ohne HTTPS: Graph sendet keine Benachrichtigungen an HTTP-Endpunkte oder an Adressen hinter Firewall oder VPN.
• Zu langsame Antworten: Aufwendige Verarbeitung im Request-Zyklus führt zu Verzögerung oder zum dauerhaften Verlust von Benachrichtigungen.
• Client-Status nicht geprüft: Gefälschte Nachrichten lassen sich dann nicht erkennen.
• Abonnement vergessen: Ohne rechtzeitige Verlängerung enden die Benachrichtigungen unbemerkt.
• Kein Fallback: Ohne Delta-Abfrage bleiben verpasste Änderungen verloren.

Praktische Takeaways

• Ersetzen Sie ständiges Polling durch Webhooks, um unnötige Anfragen, Drosselung und Verzögerungen zu vermeiden.
• Ein Abonnement braucht Benachrichtigungs-URL, Ressource, Änderungstyp und Ablaufdatum. Ein Client-Status erhöht die Sicherheit.
• Beantworten Sie den Validierungshandshake binnen 10 Sekunden als text/plain und unterstützen Sie TLS 1.2.
• Prüfen Sie bei jeder Benachrichtigung zuerst den Client-Status.
• Antworten Sie innerhalb von drei Sekunden mit einem 2xx-Status und verarbeiten Sie asynchron über eine Warteschlange.
• Verlängern Sie Abonnements per PATCH vor Ablauf und nutzen Sie Lebenszyklusbenachrichtigungen als Erinnerung.
• Kombinieren Sie Webhooks mit Delta-Abfragen und speichern Sie den jeweils aktuellen Delta-Link.
• Prüfen Sie Ihre bestehenden Abfrageprozesse, etwa für freigegebene Postfächer, SharePoint-Bibliotheken oder Benutzer-Updates für ein HR-System, auf Webhook-Potenzial.

Fazit

Microsoft Graph Webhooks verwandeln eine ständige Fragerei in ein ereignisgesteuertes Modell: Graph meldet Änderungen, Ihre App reagiert. Das spart Anfragen, vermeidet Drosselung und bringt echte Echtzeit. Damit es zuverlässig läuft, brauchen Sie einen schnellen, sicheren HTTPS-Endpunkt, eine saubere Abonnementverwaltung und Delta-Abfragen als Sicherheitsnetz. Meist müssen Sie dafür nicht alles neu bauen, sondern können bestehende Abfragen schrittweise ersetzen.