Recevoir des notifications de modification via des webhooks

  • Article

Un webhook est une API de rappel définie par l’utilisateur basée sur HTTP que vous pouvez configurer dans votre infrastructure pour recevoir des notifications de modification et des événements à partir d’un service, tel que Microsoft Graph. Pour utiliser des webhooks, vous devez définir un point de terminaison sécurisé HTTPS accessible publiquement qui recevra les notifications.

Vous pouvez créer un abonnement à la ressource pour laquelle vous souhaitez être informé des modifications. Tant que l’abonnement est valide, Microsoft Graph envoie une notification à votre point de terminaison chaque fois qu’il détecte une modification dans la ressource.

L’article vous guide tout au long du processus d’implémentation de votre point de terminaison de webhook, de l’abonnement et de la gestion des abonnements Microsoft Graph, et de la façon de recevoir des notifications de modification via des webhooks.

Pour plus d’informations sur la création de notifications de modification, consultez Notifications de modification microsoft API Graph.

Considérations relatives à un point de terminaison de webhook

Avant de recevoir une notification via des webhooks, vous devez créer un point de terminaison https accessible publiquement et adressable via une URL. Si votre point de terminaison n’est pas accessible publiquement, Microsoft Graph n’envoie pas de notifications à votre point de terminaison.

Votre point de terminaison doit fournir des réponses HTTP correctes, cohérentes et opportunes afin de recevoir des notifications de manière fiable. Si un point de terminaison ne répond pas en temps voulu, le service de notification de modification peut commencer à supprimer les notifications. Les notifications supprimées ne peuvent pas être récupérées.

Votre point de terminaison doit également continuer à rester authentifié auprès de Microsoft Graph, soit en renouvelant continuellement votre abonnement, soit en répondant aux notifications de cycle de vie.

Codes HTTP et logique de nouvelle tentative

Une fois que le service de notifications de modification Microsoft Graph reçoit un code de classe 2xx de votre point de terminaison, la notification est considérée comme envoyée. Tant que le service de notifications de modification reçoit toute autre réponse HTML (même un code d’erreur) dans les 3 secondes, le service continue d’essayer de remettre la notification pendant 4 heures maximum.

  • Si vous êtes en mesure de traiter la notification dans une fenêtre de 3 secondes, vous devez retourner un 200 - OK code status à Microsoft Graph
  • Si votre service peut prendre plus de 3 secondes pour traiter la notification, vous pouvez choisir de conserver la notification dans une file d’attente sur votre point de terminaison et de retourner 202 - Accepted status code à Microsoft Graph.
  • Si la notification n’est pas traitée ou mise en file d’attente, retournez un code de classe 5xx pour indiquer une erreur afin que Microsoft Graph puisse réessayer la notification.

Les notifications qui ne parviennent pas à être remises seront retentées à des intervalles d’interruption exponentiels. Les notifications manquées peuvent prendre jusqu’à 4 heures à renvoyer une fois que votre point de terminaison est en ligne.

Limitation

Pour des raisons de sécurité et de performances, Microsoft Graph limite les notifications envoyées aux points de terminaison qui deviennent lents ou qui ne répondent pas. Cela peut inclure la suppression des notifications de manière à ce qu’elles ne puissent pas être récupérées.

  1. Un point de terminaison est marqué comme « lent » une fois que plus de 10 % des réponses prennent plus de 3 secondes dans une fenêtre de 10 minutes.

    • Une fois qu’un point de terminaison a été marqué comme « lent », toutes les nouvelles notifications sont envoyées sur un délai de 10 secondes.
    • Un point de terminaison quitte l’état « lent » une fois que moins de 10 % des réponses prennent plus de 3 secondes dans une fenêtre de 10 minutes.

  2. Un point de terminaison est marqué comme « drop » une fois que plus de 15 % des réponses prennent plus de 3 secondes dans une fenêtre de 10 minutes.

    • Une fois qu’un point de terminaison a été marqué « drop », toutes les nouvelles notifications sont supprimées pendant jusqu’à 10 minutes.
    • Un point de terminaison quitte l’état « drop » une fois que moins de 15 % des réponses prennent plus de 3 secondes dans une fenêtre de 10 minutes.

Si votre point de terminaison n’est pas en mesure de respecter ces caractéristiques de performances, envisagez d’utiliser Event Hubs ou Event Grid comme cible pour recevoir des notifications.

Authentification

Lorsque vous créez votre abonnement, un jeton d’accès est envoyé à votre point de terminaison. Ce jeton d’accès est utilisé uniquement pour case activée la validité de votre point de terminaison et a un cycle de vie différent de celui de votre abonnement aux notifications de modification. Ce jeton d’accès expire généralement dans une heure.

Votre point de terminaison doit être prêt à se réautoriser régulièrement avec Microsoft Graph pour s’assurer que Microsoft Graph peut continuer à remettre des notifications à votre point de terminaison.

Si un jeton d’accès expire, les notifications ne sont pas remises. Toutefois, cela ne déclenche pas le comportement de limitation des points de terminaison et Microsoft Graph continuera à réessayer d’envoyer chaque notification pendant jusqu’à 4 heures. Par conséquent, si le jeton d’accès est actualisé dans les 4 heures suivant l’expiration, les notifications non envoyées sont remises.

Il est recommandé d’ajouter des notifications de cycle de vie à votre abonnement pour recevoir un avertissement concernant l’expiration du jeton afin de pouvoir réautoriser votre point de terminaison en temps voulu.

Lorsque vous renouvelez votre abonnement, votre jeton d’accès est également actualisé.

Configuration du pare-feu

Vous pouvez configurer le pare-feu qui protège votre point de terminaison pour autoriser les connexions entrantes uniquement à partir de Microsoft Graph, ce qui réduit l’exposition aux notifications de modification non valides. Pour obtenir la liste complète des adresses IP utilisées par Microsoft Graph pour transmettre des notifications de modifications, voir autres points de terminaison pour Microsoft 365.

Remarque

Les adresses IP répertoriées utilisées pour remettre des notifications de modification peuvent être mises à jour à tout moment sans préavis.

Création d’un abonnement

Importante

Plusieurs étapes sont nécessaires pour garantir l’établissement et la maintenance d’un canal de communication sécurisé entre le service de notifications de modification Microsoft Graph et votre point de terminaison.

Pour commencer à recevoir des notifications de modification Microsoft Graph, vous devez créer un abonnement à l’aide de l’URL de votre point de terminaison (URL de notification) pour établir l’abonnement. Le modèle d’établissement d’un abonnement est le suivant :

  1. L’application cliente envoie une demande d’abonnement pour s’abonner aux modifications sur une ressource spécifique.

  2. Microsoft Graph vérifie la demande.

    • Si la demande est valide, Microsoft Graph envoie un jeton de validation à l’URL de notification pour que l’application cliente valide l’URL de notification.
    • Si la demande n’est pas valide, Microsoft Graph envoie une réponse d’erreur avec un code d’erreur et des détails.

  3. Lorsque le client reçoit la demande de validation de l’URL de notification, le client répond avec le jeton de validation en texte brut.

  4. Microsoft Graph valide la réponse du jeton de validation du client et, si le jeton de validation est valide, répond avec un ID d’abonnement.

Demande d’abonnement

L’application cliente envoie une requête POST au point de /subscriptions terminaison. L’exemple suivant montre une demande de base pour s’abonner aux modifications apportées à un dossier de messagerie spécifique pour le compte de l’utilisateur connecté. Pour plus d’informations sur les autres ressources Microsoft Graph qui prennent en charge les notifications de modification, consultez ressources prises en charge.

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"
}

La propriété clientState est obligatoire. La définition de cette propriété permet à votre service de confirmer que les notifications de modification que vous recevez proviennent de Microsoft Graph. Pour cette raison, la valeur de la propriété doit rester secrète et connue uniquement de votre application et du service Microsoft Graph.

En cas de réussite, Microsoft Graph renvoie un code 201 Created et un objet subscription dans le corps.

Chaque abonnement a un id d’abonnement unique, même si vous avez plusieurs abonnements qui surveillent la même ressource et utilisent la même URL de notification.

Remarque

Tout paramètre de chaîne de requête inclus dans la propriété notificationUrl est inclus dans la requête HTTP POST lorsque des notifications sont remises à votre service.

Remarque

Les abonnements en double ne sont pas autorisés. Lorsqu’une demande d’abonnement contient les mêmes valeurs pour changeType et resource qu’un abonnement existant, la requête échoue avec un code 409 Conflictd’erreur HTTP et le message Subscription Id <> already exists for the requested combinationd’erreur .

validation notificationUrl

Lorsque vous envoyez une demande de création d’un abonnement pour recevoir des notifications de modification par le biais de webhooks, Microsoft Graph vérifie si la propriété notificationUrl dans votre demande d’abonnement est valide. Le processus de validation fonctionne comme suit :

Remarque

Si vous vous abonnez également aux notifications de cycle de vie , Microsoft Graph valide également le lifecycleNotificationUrl.

  1. Lorsqu’un abonnement est demandé, Microsoft Graph encode un jeton de validation et l’inclut dans une requête POST à l’URL de notification comme suit.

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

  2. Le client doit décoder correctement l’URL pour obtenir le jeton de validation de texte brut à partir de Microsoft Graph.

    L’échappement de code HTML ou JavaScript est une bonne pratique, car les acteurs malveillants peuvent utiliser le point de terminaison de notification pour le type d’attaques de script intersites. Microsoft Graph n’envoie jamais de valeur contenant du code HTML ou JavaScript.

    En général, traitez la valeur du jeton de validation comme opaque, car le format du jeton peut changer sans préavis.

  3. Le client doit répondre avec les caractéristiques suivantes dans les 10 secondes suivant l’étape 1 :

    • Un code d’état de HTTP 200 OK.
    • Type de contenu de text/plain.
    • Corps qui inclut le jeton de validation de texte brut décodé par URL .

    Importante

    Le jeton de validation doit être retourné en texte brut. Si le client retourne un jeton de validation encodé, la validation échoue.

  4. Si la validation du point de terminaison échoue, Microsoft Graph ne crée pas l’abonnement.

Recevoir des notifications

Bien que l’abonnement soit valide et qu’il y ait des modifications apportées à la ressource à laquelle vous vous êtes abonné, Microsoft Graph envoie une POST demande à notificationUrl avec les détails des modifications. Cette charge utile est la notification de modification.

Pour la plupart des abonnements, Microsoft Graph ne retarde pas l’envoi de notifications, mais remet toutes les notifications dans le contrat SLA, sauf si le service rencontre un incident.

Une charge utile de notification de modification envoyée à votre point de terminaison peut contenir une collection de notifications de modification relatives à vos abonnements.

Exemple de notification de modifications

Lorsque l’utilisateur reçoit un e-mail, Microsoft Graph envoie un objet de notification de modification à l’application cliente, comme illustré dans l’exemple suivant. Pour plus d’informations sur la charge utile de notification, consultez changeNotificationCollection et changeNotification associée.

Lorsque de nombreuses modifications se produisent, Microsoft Graph peut envoyer plusieurs notifications qui correspondent à différents abonnements au sein d’une même demande de POST.

{
  "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}"
      }
    }
  ]
}

Traitement de la notification de modifications

Lorsque vous recevez une notification de modification :

  1. Validez la propriété clientState . Elle doit correspondre à la valeur envoyée initialement avec la demande de la création de l’abonnement.

    En cas d’incompatibilité, ne considérez pas la notification de modification comme valide. Il est possible que la notification de modification ne provient pas de Microsoft Graph et qu’elle ait été envoyée par un acteur non autorisé. Vous devez également examiner la provenance de la notification de modifications et prendre les mesures qui s’imposent.

  2. Mettez à jour votre application cliente en fonction de votre logique métier.

Cycle de vie de l’abonnement

Lorsqu’ils ne sont plus nécessaires, les abonnements peuvent être supprimés ou expirent. Lorsque vous créez votre abonnement, vous définissez une date d’expiration à l’aide de la propriété expirationDateTime . Une fois ce délai dépassé, Microsoft Graph supprime l’abonnement et n’envoie pas de notifications à votre point de terminaison. Vous pouvez également supprimer explicitement votre abonnement.

Le moyen le plus simple de continuer à recevoir des notifications consiste à continuer à renouveler votre demande d’abonnement. Chaque notification inclut une propriété subscriptionExpirationDateTime . Vous pouvez l’utiliser pour vous guider quand renouveler votre abonnement.

Chaque abonnement inclut également un jeton d’accès accordé au point de terminaison. L’heure d’expiration de ce jeton d’accès peut se produire avant l’expiration de l’abonnement. Vous pouvez gérer l’expiration du jeton d’accès à l’aide des notifications de cycle de vie pour votre abonnement.

Renouveler un abonnement

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

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

Si la demande de renouvellement d’abonnement réussit, Microsoft Graph renvoie un 200 OK code de réponse et un objet d’abonnement dans le corps de la réponse. L’objet subscription inclut la nouvelle valeur expirationDateTime .

Suppression d’un abonnement

Si l’application cliente ne souhaite plus recevoir de notifications de modification, elle peut supprimer l’abonnement à l’aide de son id d’abonnement comme suit :

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

En cas de réussite, Microsoft Graph renvoie un code 204 No Content.

Notifications de cycle de vie pour votre abonnement

Pour plus de flexibilité et de fiabilité, lorsque vous créez un abonnement, vous pouvez également vous abonner aux notifications de cycle de vie de cet abonnement en fournissant un point de terminaison lifecycleNotificationUrl qui recevra, traitera et répondra aux notifications de cycle de vie.

Lorsque vous vous abonnez aux notifications de cycle de vie, Microsoft Graph vous avertit :

  • Lorsque le jeton d’accès est sur le point d’expirer.
  • Lorsqu’un abonnement est sur le point d’expirer.
  • Lorsqu’un administrateur client a révoqué les autorisations de votre application pour lire une ressource.

Remarque

Si un jeton d’accès expire, les notifications ne sont pas remises au point de terminaison. Toutefois, Microsoft Graph continuera à réessayer d’envoyer chaque notification pendant 4 heures maximum. Par conséquent, si le jeton d’accès est actualisé dans les 4 heures suivant l’expiration, les notifications non envoyées sont remises.

Pour plus d’informations sur l’utilisation des notifications de cycle de vie pour votre abonnement, consultez Notifications de cycle de vie.

Résumé

Dans cet article, vous avez appris à recevoir des notifications de modification via des webhooks.

  1. Créez un abonnement en envoyant une requête POST au point de /subscriptions terminaison.
  2. Microsoft Graph valide le point de terminaison de notification de webhook avant de terminer le processus de création de l’abonnement. Un id d’abonnement unique est lié à l’abonnement.
  3. Tant que l’abonnement est toujours valide et que des modifications se produisent sur la ressource abonnée, Microsoft Graph envoie des notifications de modification au point de terminaison notificationUrl .
  4. Renouvelez régulièrement l’abonnement pour conserver sa validité et continuer à recevoir des mises à jour sur les modifications souscrites.

Contenu connexe