Empfangen von Änderungsbenachrichtigungen über Webhooks

  • Artikel

Ein Webhook ist eine HTTP-basierte benutzerdefinierte Rückruf-API, die Sie in Ihrer Infrastruktur einrichten können, um Änderungsbenachrichtigungen und Ereignisse von einem Dienst wie Microsoft Graph zu empfangen. Um Webhooks verwenden zu können, müssen Sie einen öffentlich zugänglichen HTTPS-gesicherten Endpunkt definieren, der die Benachrichtigungen empfängt.

Sie können ein Abonnement für die Ressource erstellen, für die Sie über Änderungen benachrichtigt werden möchten. Solange das Abonnement gültig ist, sendet Microsoft Graph eine Benachrichtigung an Ihren Endpunkt, wenn eine Änderung an der Ressource erkannt wird.

Der Artikel führt Sie durch den Prozess der Implementierung Ihres Webhook-Endpunkts, das Abonnieren und Verwalten von Microsoft Graph-Abonnements und das Empfangen von Änderungsbenachrichtigungen über Webhooks.

Ausführliche Informationen zum Erstellen von Änderungsbenachrichtigungen finden Sie unter Microsoft Graph-API Änderungsbenachrichtigungen.

Überlegungen zu einem Webhookendpunkt

Bevor Sie eine Benachrichtigung über Webhooks erhalten können, müssen Sie einen öffentlich zugänglichen, HTTPS-gesicherten Endpunkt erstellen, der über eine URL adressierbar ist. Wenn Ihr Endpunkt nicht öffentlich zugänglich ist, sendet Microsoft Graph keine Benachrichtigungen an Ihren Endpunkt.

Ihr Endpunkt muss korrekte, konsistente und zeitnahe HTTP-Antworten bereitstellen, um Benachrichtigungen zuverlässig empfangen zu können. Wenn ein Endpunkt nicht rechtzeitig antwortet, beginnt der Änderungsbenachrichtigungsdienst möglicherweise, Benachrichtigungen zu löschen. Verworfene Benachrichtigungen können nicht wiederhergestellt werden.

Ihr Endpunkt muss auch weiterhin bei Microsoft Graph authentifiziert bleiben, entweder durch kontinuierliche Verlängerung Ihres Abonnements oder durch Reagieren auf Lebenszyklusbenachrichtigungen.

HTTP-Codes und Wiederholungslogik

Sobald der Microsoft Graph-Änderungsbenachrichtigungsdienst einen 2xx-Klassencode von Ihrem Endpunkt empfängt, gilt die Benachrichtigung als gesendet. Solange der Änderungsbenachrichtigungsdienst innerhalb von 3 Sekunden eine andere HTML-Antwort (auch einen Fehlercode) empfängt, versucht der Dienst, die Benachrichtigung für bis zu vier Stunden zu übermitteln.

  • Wenn Sie die Benachrichtigung innerhalb eines 3-Sekunden-Fensters verarbeiten können, sollten Sie einen 200 - OK status Code an Microsoft Graph zurückgeben.
  • Wenn ihr Dienst mehr als 3 Sekunden benötigt, um die Benachrichtigung zu verarbeiten, können Sie die Benachrichtigung in einer Warteschlange an Ihrem Endpunkt beibehalten und status Code an Microsoft Graph zurückgeben 202 - Accepted .
  • Wenn die Benachrichtigung nicht verarbeitet oder in die Warteschlange gestellt wird, geben Sie einen 5xx-Klassencode zurück, um einen Fehler anzugeben, damit Microsoft Graph die Benachrichtigung wiederholen kann.

Benachrichtigungen, die nicht übermittelt werden können, werden in exponentiellen Backoffintervallen wiederholt. Verpasste Benachrichtigungen können bis zu 4 Stunden dauern, bis sie erneut gesendet werden, sobald Ihr Endpunkt online geschaltet wird.

Einschränkung

Aus Sicherheits- und Leistungsgründen drosselt Microsoft Graph Benachrichtigungen, die an Endpunkte gesendet werden, die langsam oder nicht mehr reagieren. Dies kann das Löschen von Benachrichtigungen auf eine Weise umfassen, die nicht wiederhergestellt werden kann.

  1. Ein Endpunkt wird als "langsam" gekennzeichnet, sobald mehr als 10 % der Antworten länger als 3 Sekunden in einem Zehn-Minuten-Fenster dauern.

    • Sobald ein Endpunkt als "langsam" gekennzeichnet wurde, werden alle neuen Benachrichtigungen mit einer Verzögerung von 10 Sekunden gesendet.
    • Ein Endpunkt beendet den "langsamen" Zustand, sobald weniger als 10 % der Antworten länger als 3 Sekunden in einem 10-Minuten-Fenster dauern.

  2. Ein Endpunkt wird als "Löschen" markiert, sobald mehr als 15 % der Antworten länger als 3 Sekunden in einem 10-Minuten-Fenster dauern.

    • Sobald ein Endpunkt als "drop" markiert wurde, werden alle neuen Benachrichtigungen für bis zu 10 Minuten gelöscht.
    • Ein Endpunkt beendet den Zustand "Löschen", sobald weniger als 15 % der Antworten länger als 3 Sekunden in einem 10-Minuten-Fenster dauern.

Wenn Ihr Endpunkt diese Leistungsmerkmale nicht erfüllen kann, erwägen Sie die Verwendung von Event Hubs oder Event Grid als Ziel für den Empfang von Benachrichtigungen.

Authentifizierung

Wenn Sie Ihr Abonnement erstellen, wird ein Zugriffstoken an Ihren Endpunkt gesendet. Dieses Zugriffstoken wird nur verwendet, um die Gültigkeit Ihres Endpunkts zu überprüfen, und hat einen anderen Lebenszyklus als Ihr Änderungsbenachrichtigungsabonnement. Dieses Zugriffstoken läuft in der Regel innerhalb einer Stunde ab.

Ihr Endpunkt muss auf die regelmäßige erneute Autorisierung mit Microsoft Graph vorbereitet sein, um sicherzustellen, dass Microsoft Graph weiterhin Benachrichtigungen an Ihren Endpunkt senden kann.

Wenn ein Zugriffstoken abläuft, werden keine Benachrichtigungen zugestellt. Dies löst jedoch kein Endpunktdrosselungsverhalten aus, und Microsoft Graph versucht weiterhin, jede Benachrichtigung für bis zu vier Stunden zu senden. Wenn das Zugriffstoken also innerhalb von vier Stunden nach Ablauf aktualisiert wird, werden nicht gesendete Benachrichtigungen zugestellt.

Es wird empfohlen, Ihrem Abonnement Lebenszyklusbenachrichtigungen hinzuzufügen, um Warnungen zum Tokenablauf zu erhalten, damit Sie Ihren Endpunkt rechtzeitig erneut authentifizieren können.

Wenn Sie Ihr Abonnement verlängern, wird auch Ihr Zugriffstoken aktualisiert.

Firewallkonfiguration

Sie können die Firewall, die Ihren Endpunkt schützt, so konfigurieren, dass nur eingehende Verbindungen von Microsoft Graph zugelassen werden, wodurch die Gefährdung durch ungültige Änderungsbenachrichtigungen weiter reduziert wird. Eine vollständige Liste der IP-Adressen, die von Microsoft Graph zur Übermittlung von Änderungsbenachrichtigungen verwendet werden, finden Sie unter Zusätzliche Endpunkte für Microsoft 365.

Hinweis

Die aufgeführten IP-Adressen, die zur Übermittlung von Änderungsbenachrichtigungen verwendet werden, können jederzeit ohne Vorankündigung aktualisiert werden.

Erstellen eines Abonnements

Wichtig

Es sind mehrere Schritte erforderlich, um sicherzustellen, dass ein sicherer Kommunikationskanal zwischen dem Microsoft Graph-Änderungsbenachrichtigungsdienst und Ihrem Endpunkt eingerichtet und verwaltet wird.

Um Microsoft Graph-Änderungsbenachrichtigungen zu erhalten, müssen Sie ein Abonnement erstellen, indem Sie die URL Ihres Endpunkts (Benachrichtigungs-URL) verwenden, um das Abonnement einzurichten. Das Muster zum Einrichten eines Abonnements sieht wie folgt aus:

  1. Die Client-App sendet eine Abonnementanforderung zum Abonnieren von Änderungen an einer bestimmten Ressource.

  2. Microsoft Graph überprüft die Anforderung.

    • Wenn die Anforderung gültig ist, sendet Microsoft Graph ein Validierungstoken an die Benachrichtigungs-URL für die Client-App, um die Benachrichtigungs-URL zu überprüfen.
    • Wenn die Anforderung ungültig ist, sendet Microsoft Graph eine Fehlerantwort mit einem Fehlercode und Details.

  3. Wenn der Client die Überprüfungsanforderung für die Benachrichtigungs-URL empfängt, antwortet der Client mit dem Validierungstoken im Klartext.

  4. Microsoft Graph überprüft die Antwort des Client-Validierungstokens, und wenn das Validierungstoken gültig ist, antwortet mit einer Abonnement-ID.

Abonnementanforderung

Die Client-App sendet eine POST-Anforderung an den /subscriptions Endpunkt. Das folgende Beispiel zeigt eine einfache Anforderung zum Abonnieren von Änderungen an einem bestimmten E-Mail-Ordner im Namen des angemeldeten Benutzers. Weitere Informationen zu anderen Microsoft Graph-Ressourcen, die Änderungsbenachrichtigungen unterstützen, finden Sie unter Unterstützte Ressourcen.

POST https://graph.microsoft.com/v1.0/subscriptions
Content-Type: application/json

{
  "changeType": "created,updated",
  "notificationUrl": "https://webhook.azurewebsites.net/notificationClient",
  "lifecycleNotificationUrl": "https://webhook.azurewebsites.net/api/lifecycleNotifications",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}

Die clientState-Eigenschaft ist erforderlich. Durch Festlegen dieser Eigenschaft kann Ihr Dienst bestätigen, dass Änderungsbenachrichtigungen, die Sie erhalten, von Microsoft Graph stammen. Aus diesem Grund muss der Wert der Eigenschaft geheim bleiben und darf nur der Anwendung und dem Microsoft Graph-Dienst bekannt sein.

Wenn der Vorgang erfolgreich war, gibt Microsoft Graph einen 201 Created-Code und ein subscription-Objekt im Textkörper zurück.

Jedes Abonnement verfügt über eine eindeutige subscriptionId, auch wenn Sie über mehrere Abonnements verfügen, die dieselbe Ressource überwachen und dieselbe Benachrichtigungs-URL verwenden.

Hinweis

Alle Abfragezeichenfolgenparameter, die in der notificationUrl-Eigenschaft enthalten sind, werden in die HTTP POST-Anforderung eingeschlossen, wenn Benachrichtigungen an Ihren Dienst übermittelt werden.

Hinweis

Doppelte Abonnements sind nicht zulässig. Wenn eine Abonnementanforderung die gleichen Werte für changeType und ressource wie ein vorhandenes Abonnement enthält, schlägt die Anforderung mit einem HTTP-Fehlercode 409 Conflictund der Fehlermeldung Subscription Id <> already exists for the requested combinationfehl.

notificationUrl-Überprüfung

Wenn Sie eine Anforderung zum Erstellen eines Abonnements senden, um Änderungsbenachrichtigungen über Webhooks zu erhalten, überprüft Microsoft Graph, ob die notificationUrl-Eigenschaft in Ihrer Abonnementanforderung gültig ist. Der Validierungsprozess funktioniert wie folgt:

Hinweis

Wenn Sie auch Lebenszyklusbenachrichtigungen abonnieren, überprüft Microsoft Graph auch lifecycleNotificationUrl.

  1. Wenn ein Abonnement angefordert wird, codiert Microsoft Graph ein Validierungstoken und schließt es wie folgt in eine POST-Anforderung an die Benachrichtigungs-URL ein.

    Content-Type: text/plain; charset=utf-8
POST https://{notificationUrl}?validationToken={opaqueTokenCreatedByMicrosoftGraph}

  2. Der Client muss die URL ordnungsgemäß decodieren, um das Nur-Text-Validierungstoken von Microsoft Graph abzurufen.

    Das Escapen von HTML- oder JavaScript-Code ist eine bewährte Methode, da böswillige Akteure den Benachrichtigungsendpunkt für websiteübergreifende Skripts verwenden können. Microsoft Graph sendet niemals einen Wert, der HTML- oder JavaScript-Code enthält.

    Im Allgemeinen sollten Sie den Wert des Validierungstokens als undurchsichtig behandeln, da sich das Tokenformat ohne Vorheriges ändern kann.

  3. Der Client muss innerhalb von 10 Sekunden nach Schritt 1 mit den folgenden Merkmalen antworten:

    • Statuscode HTTP 200 OK.
    • Inhaltstyp text/plain.
    • Ein Text, der das URL-decodierte Nur-Text-Validierungstoken enthält.

    Wichtig

    Das Validierungstoken muss als Nur-Text zurückgegeben werden. Wenn der Client ein codiertes Überprüfungstoken zurückgibt, tritt bei der Überprüfung ein Fehler auf.

  4. Wenn die Endpunktüberprüfung fehlschlägt, erstellt Microsoft Graph das Abonnement nicht.

Empfangen von Benachrichtigungen

Während das Abonnement gültig ist und Änderungen an der Ressource vorliegen, die Sie abonniert haben, sendet Microsoft Graph eine POST Anforderung mit Details zu den Änderungen an notificationUrl . Diese Nutzlast ist die Änderungsbenachrichtigung.

Bei den meisten Abonnements verzögert Microsoft Graph das Senden von Benachrichtigungen nicht, sondern übermittelt alle Benachrichtigungen innerhalb der SLA, es sei denn, es tritt ein Vorfall auf.

Eine Änderungsbenachrichtigungsnutzlast, die an Ihren Endpunkt gesendet wird, kann eine Sammlung von Änderungsbenachrichtigungen für Ihre Abonnements enthalten.

Beispiel für eine Änderungsbenachrichtigung

Wenn der Benutzer eine E-Mail erhält, sendet Microsoft Graph ein Änderungsbenachrichtigungsobjekt an die Client-App, wie im folgenden Beispiel gezeigt. Weitere Informationen zur Benachrichtigungsnutzlast finden Sie unter changeNotificationCollection und die zugehörige changeNotification .

Wenn zahlreiche Änderungen vorgenommen werden, kann Microsoft Graph mehrere Benachrichtigungen senden, die verschiedenen Abonnements in derselben POST-Anforderung entsprechen.

{
  "value": [
    {
      "id": "lsgTZMr9KwAAA",
      "subscriptionId":"{subscription_guid}",
      "subscriptionExpirationDateTime":"2016-03-19T22:11:09.952Z",
      "clientState":"secretClientValue",
      "changeType":"created",
      "resource":"users/{user_guid}@{tenant_guid}/messages/{long_id_string}",
      "tenantId": "84bd8158-6d4d-4958-8b9f-9d6445542f95",
      "resourceData":
      {
        "@odata.type":"#Microsoft.Graph.Message",
        "@odata.id":"Users/{user_guid}@{tenant_guid}/Messages/{long_id_string}",
        "@odata.etag":"W/\"CQAAABYAAADkrWGo7bouTKlsgTZMr9KwAAAUWRHf\"",
        "id":"{long_id_string}"
      }
    }
  ]
}

Verarbeiten der Änderungsbenachrichtigung

Wenn Sie eine Änderungsbenachrichtigung erhalten:

  1. Überprüfen Sie die clientState-Eigenschaft . Sie muss dem Wert entsprechen, der ursprünglich mit der Anforderung zum Erstellen eines Abonnement übermittelt wurde.

    Wenn ein Konflikt vorliegt, betrachten Sie die Änderungsbenachrichtigung nicht als gültig. Es ist möglich, dass die Änderungsbenachrichtigung nicht von Microsoft Graph stammt und möglicherweise von einem nicht autorisierten Akteur gesendet wurde. Prüfen Sie auch, woher die Änderungsbenachrichtigung stammt, und ergreifen Sie die entsprechenden Maßnahmen.

  2. Aktualisieren Sie Ihre Client-App basierend auf Ihrer Geschäftslogik.

Abonnementlebenszyklus

Wenn sie nicht mehr benötigt werden, werden Abonnements möglicherweise gelöscht oder laufen ab. Wenn Sie Ihr Abonnement erstellen, legen Sie mithilfe der expirationDateTime-Eigenschaft ein Ablaufdatum fest. Sobald diese Zeit abgelaufen ist, löscht Microsoft Graph das Abonnement und sendet keine Benachrichtigungen an Ihren Endpunkt. Sie können Ihr Abonnement auch explizit löschen.

Die einfachste Möglichkeit, weiterhin Benachrichtigungen zu erhalten, besteht darin, Ihre Abonnementanforderung weiterhin zu verlängern. Jede Benachrichtigung enthält eine subscriptionExpirationDateTime-Eigenschaft . Anhand dieser Informationen können Sie ermitteln, wann Sie Ihr Abonnement verlängern müssen.

Jedes Abonnement enthält auch ein Zugriffstoken, das dem Endpunkt gewährt wird. Die Ablaufzeit dieses Zugriffstokens kann vor dem Ablauf des Abonnements auftreten. Sie können den Ablauf von Zugriffstoken mithilfe von Lebenszyklusbenachrichtigungen für Ihr Abonnement verwalten.

Verlängern eines Abonnements

PATCH https://graph.microsoft.com/v1.0/subscriptions/{id}
Content-Type: application/json

{
  "expirationDateTime": "2016-03-22T11:00:00.0000000Z"
}

Wenn die Anforderung zur Abonnementverlängerung erfolgreich ist, gibt Microsoft Graph einen 200 OK Antwortcode und ein Abonnementobjekt im Antworttext zurück. Das Abonnementobjekt enthält den neuen expirationDateTime-Wert .

Löschen eines Abonnements

Wenn die Client-App keine Änderungsbenachrichtigungen mehr wünscht, kann sie das Abonnement mit ihrer subscriptionId wie folgt löschen:

DELETE https://graph.microsoft.com/v1.0/subscriptions/{id}

Wenn der Vorgang erfolgreich verläuft, gibt Microsoft Graph einen 204 No Content-Code zurück.

Lebenszyklusbenachrichtigungen für Ihr Abonnement

Um mehr Flexibilität und Zuverlässigkeit zu erzielen, können Sie beim Erstellen eines Abonnements auch die Lebenszyklusbenachrichtigungen für dieses Abonnement abonnieren, indem Sie einen lifecycleNotificationUrl-Endpunkt bereitstellen, der Lebenszyklusbenachrichtigungen empfängt, verarbeitet und darauf reagiert.

Wenn Sie Lebenszyklusbenachrichtigungen abonnieren, warnt Microsoft Graph Sie:

  • Wenn das Zugriffstoken bald abläuft.
  • Wenn ein Abonnement bald abläuft.
  • Wenn ein Mandantenadministrator die Berechtigungen Ihrer App zum Lesen einer Ressource widerrufen hat.

Hinweis

Wenn ein Zugriffstoken abläuft, werden keine Benachrichtigungen an den Endpunkt übermittelt. Microsoft Graph versucht jedoch weiterhin, jede Benachrichtigung für bis zu vier Stunden zu senden. Wenn das Zugriffstoken also innerhalb von vier Stunden nach Ablauf aktualisiert wird, werden nicht gesendete Benachrichtigungen zugestellt.

Weitere Informationen zur Verwendung von Lebenszyklusbenachrichtigungen für Ihr Abonnement finden Sie unter Lebenszyklusbenachrichtigungen.

Zusammenfassung

In diesem Artikel haben Sie erfahren, wie Sie Änderungsbenachrichtigungen über Webhooks erhalten.

  1. Erstellen Sie ein Abonnement, indem Sie eine POST-Anforderung an den /subscriptions Endpunkt senden.
  2. Microsoft Graph überprüft den Webhook-Benachrichtigungsendpunkt, bevor er den Erstellungsprozess des Abonnements abgeschlossen hat. Eine eindeutige subscriptionId ist mit dem Abonnement verknüpft.
  3. Solange das Abonnement noch gültig ist und Änderungen an der abonnierten Ressource auftreten, sendet Microsoft Graph Änderungsbenachrichtigungen an den notificationUrl-Endpunkt .
  4. Verlängern Sie das Abonnement regelmäßig, um seine Gültigkeit zu behalten und weiterhin Updates zu den abonnierten Änderungen zu erhalten.

Verwandte Inhalte