Recevoir des notifications de modification via des webhooks

Article
03/26/2023
13 minutes de lecture

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 d’un service, tel que Microsoft Graph. Vous devez configurer le webhook à l’aide d’un point de terminaison sécurisé HTTPS connu et accessible.

Pour recevoir des notifications de modification via des webhooks, vous devez créer un abonnement à la ressource pour laquelle vous souhaitez être informé des modifications. Lorsque l’abonnement est valide, Microsoft Graph envoie une notification à votre application chaque fois qu’une modification est détectée sur la ressource.

L’article vous guide tout au long du processus de gestion de votre abonnement Microsoft Graph et comment recevoir des notifications de modification via des webhooks.

Création d’un abonnement

Avant de recevoir des notifications de modification Microsoft Graph, vous devez d’abord créer un abonnement. Le processus de configuration d’un abonnement valide implique l’application cliente et Microsoft Graph comme suit :

L’application cliente envoie une demande d’abonnement pour s’abonner aux modifications sur une ressource spécifique.
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.
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, comme expliqué plus loin dans cet article.
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 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",
  "resource": "/me/mailfolders('inbox')/messages",
  "expirationDateTime": "2016-03-20T11:00:00.0000000Z",
  "clientState": "SecretClientState"
}


var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ChangeType = "created,updated",
	NotificationUrl = "https://webhook.azurewebsites.net/notificationClient",
	Resource = "/me/mailfolders('inbox')/messages",
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-20T11:00:00.0000000Z"),
	ClientState = "SecretClientState",
};
var result = await graphClient.Subscriptions.PostAsync(requestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  changeType: 'created,updated',
  notificationUrl: 'https://webhook.azurewebsites.net/notificationClient',
  resource: '/me/mailfolders(\'inbox\')/messages',
  expirationDateTime: '2016-03-20T11:00:00.0000000Z',
  clientState: 'SecretClientState'
};

await client.api('/subscriptions')
	.post(subscription);


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.changeType = "created,updated";
subscription.notificationUrl = "https://webhook.azurewebsites.net/notificationClient";
subscription.resource = "/me/mailfolders('inbox')/messages";
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-20T11:00:00Z");
subscription.clientState = "SecretClientState";

graphClient.subscriptions()
	.buildRequest()
	.post(subscription);


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestBody := graphmodels.NewSubscription()
changeType := "created,updated"
requestBody.SetChangeType(&changeType) 
notificationUrl := "https://webhook.azurewebsites.net/notificationClient"
requestBody.SetNotificationUrl(&notificationUrl) 
resource := "/me/mailfolders('inbox')/messages"
requestBody.SetResource(&resource) 
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-20T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 
clientState := "SecretClientState"
requestBody.SetClientState(&clientState) 

result, err := graphClient.Subscriptions().Post(context.Background(), requestBody, nil)


Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	ChangeType = "created,updated"
	NotificationUrl = "https://webhook.azurewebsites.net/notificationClient"
	Resource = "/me/mailfolders('inbox')/messages"
	ExpirationDateTime = [System.DateTime]::Parse("2016-03-20T11:00:00.0000000Z")
	ClientState = "SecretClientState"
}

New-MgSubscription -BodyParameter $params


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setChangeType('created,updated');

$requestBody->setNotificationUrl('https://webhook.azurewebsites.net/notificationClient');

$requestBody->setResource('/me/mailfolders(\'inbox\')/messages');

$requestBody->setExpirationDateTime(new DateTime('2016-03-20T11:00:00.0000000Z'));

$requestBody->setClientState('SecretClientState');



$requestResult = $graphServiceClient->subscriptions()->post($requestBody);

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.

validation notificationUrl

Lorsque vous créez un abonnement pour recevoir des notifications de modification via des webhooks, Microsoft Graph valide d’abord le point de terminaison de notification fourni dans la propriété notificationUrl de la demande d’abonnement. Le processus de validation se déroule de la façon suivante :

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}

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.
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.

Vous pouvez également utiliser la collection Microsoft Postman Graph pour confirmer que votre point de terminaison applique correctement la demande de validation. La demande de Validation de l'abonnement dans le dossier Divers offre des tests d’unités qui valident la réponse fournie par votre point de terminaison.

résultats des tests de la réponse de validation

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 application 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

Votre service doit traiter chaque notification de modification qu’il reçoit. Les tâches minimales que votre application doit effectuer pour traiter une notification de modifications sont les suivantes :

Après avoir reçu la notification de modification, renvoyez un code de classe 2xx à Microsoft Graph. Si Microsoft Graph ne reçoit pas de code de classe 2xx dans les 3 secondes, il tente de renvoyer la notification de modification plusieurs fois, pendant 4 heures maximum. Si Microsoft Graph ne reçoit toujours pas de code 2xx pendant la période, il ignore la notification de modification. Si l’application cliente ne répond pas constamment dans les 3 secondes, les notifications peuvent être soumises à une limitation.

Si votre service peut prendre plus de 3 secondes pour traiter la notification de modification, il doit conserver la notification, retourner un 202 - Accepted code status dans la réponse à Microsoft Graph, puis traiter les notifications à sa capacité. Si la notification n’est pas persistante, retournez un code de classe 5xx pour indiquer une erreur afin que Microsoft Graph puisse réessayer la notification.

Si votre service est censé prendre moins de 3 secondes, il doit traiter les notifications et retourner un 200 - OK code status à Microsoft Graph. Si la notification n’est pas traitée correctement, retournez un code de classe 5xx pour indiquer une erreur afin que Microsoft Graph puisse réessayer la notification.
Valider 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.
Mettez à jour votre application cliente en fonction de votre logique métier.

Renouveler un abonnement

Il existe de nombreuses raisons pour lesquelles vous devrez peut-être renouveler un abonnement. Pour plus d’informations, consultez Notifications de cycle de vie.

Lorsque vous vous abonnez aux notifications de cycle de vie, Microsoft Graph vous avertit lorsqu’un abonnement arrive à expiration et doit être renouvelé. Si vous ne vous abonnez pas aux notifications de cycle de vie, vous pouvez utiliser subscriptionExpirationDateTime pour surveiller quand votre application doit envoyer une demande de renouvellement d’abonnement.

Pour renouveler l’abonnement, la propriété expirationDateTime est requise. Si vous ne renouvelez pas un abonnement à temps, Microsoft Graph supprime l’abonnement et l’application ne recevra pas de notifications de modification ultérieures pour l’abonnement.

Demande de renouvellement d’abonnement

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

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


var graphClient = new GraphServiceClient(requestAdapter);

var requestBody = new Subscription
{
	ExpirationDateTime = DateTimeOffset.Parse("2016-03-22T11:00:00.0000000Z"),
};
var result = await graphClient.Subscriptions["{subscription-id}"].PatchAsync(requestBody);


const options = {
	authProvider,
};

const client = Client.init(options);

const subscription = {
  expirationDateTime: '2016-03-22T11:00:00.0000000Z'
};

await client.api('/subscriptions/{id}')
	.update(subscription);


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

Subscription subscription = new Subscription();
subscription.expirationDateTime = OffsetDateTimeSerializer.deserialize("2016-03-22T11:00:00Z");

graphClient.subscriptions("{id}")
	.buildRequest()
	.patch(subscription);


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)

requestBody := graphmodels.NewSubscription()
expirationDateTime , err := time.Parse(time.RFC3339, "2016-03-22T11:00:00.0000000Z")
requestBody.SetExpirationDateTime(&expirationDateTime) 

result, err := graphClient.SubscriptionsById("subscription-id").Patch(context.Background(), requestBody, nil)


Import-Module Microsoft.Graph.ChangeNotifications

$params = @{
	ExpirationDateTime = [System.DateTime]::Parse("2016-03-22T11:00:00.0000000Z")
}

Update-MgSubscription -SubscriptionId $subscriptionId -BodyParameter $params


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);

$requestBody = new Subscription();
$requestBody->setExpirationDateTime(new DateTime('2016-03-22T11:00:00.0000000Z'));



$requestResult = $graphServiceClient->subscriptionsById('subscription-id')->patch($requestBody);

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}


var graphClient = new GraphServiceClient(requestAdapter);

await graphClient.Subscriptions["{subscription-id}"].DeleteAsync();


const options = {
	authProvider,
};

const client = Client.init(options);

await client.api('/subscriptions/{id}')
	.delete();


GraphServiceClient graphClient = GraphServiceClient.builder().authenticationProvider( authProvider ).buildClient();

graphClient.subscriptions("{id}")
	.buildRequest()
	.delete();


//THE GO SDK IS IN PREVIEW. NON-PRODUCTION USE ONLY
graphClient := msgraphsdk.NewGraphServiceClientWithCredentials(cred, scopes)


graphClient.SubscriptionsById("subscription-id").Delete(context.Background(), nil)


Import-Module Microsoft.Graph.ChangeNotifications

Remove-MgSubscription -SubscriptionId $subscriptionId


<?php

// THIS SNIPPET IS A PREVIEW FOR THE KIOTA BASED SDK. NON-PRODUCTION USE ONLY
$graphServiceClient = new GraphServiceClient($requestAdapter);


$graphServiceClient->subscriptionsById('subscription-id')->delete();

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

Limitation

Si une URL de notification d’abonnement est lente ou ne répond pas et que Microsoft Graph ne reçoit pas de code de classe 2xx dans les 3 secondes, Microsoft Graph tente de renvoyer la notification de modification plusieurs fois, pendant 4 heures maximum. Dans ce cas, Microsoft Graph peut limiter les notifications pour le point de terminaison de notification associé à l’abonnement.

Comment Microsoft Graph gère la limitation pour les notifications de modification à l’aide de webhooks

Les notifications sont publiées à l’aide d’un client HTTP avec un délai d’expiration de 3 secondes.

Si la durée de publication est supérieure à 2900 ms, la réponse est considérée comme lente.
Le service de notification de modification calcule ensuite le pourcentage de réponses lentes après que le point de terminaison a reçu 100 notifications.
Si le pourcentage de réponses lentes atteint 10 %, le point de terminaison associé à l’URL de notification est marqué comme point de terminaison lent. Toutes les notifications pour tous les abonnements associés au point de terminaison sont soumises à une limitation.
L’évaluation se poursuit en temps réel et l’accumulation des réponses est vidée toutes les 10 minutes.

Lorsque Microsoft Graph limite un point de terminaison, les notifications sont soumises à un délai de 10 minutes et sont déchargées vers les workers dédiés aux notifications ayant échoué et limitée. Les notifications qui n’ont pas réussi en raison d’un appel HTTP infructueux sont de nouveau retentées dans 10 minutes. Les notifications sont supprimées si le pourcentage de lenteur du point de terminaison limité est supérieur ou égal à 15 %.

Configuration du pare-feu

Vous pouvez configurer le pare-feu qui protège votre URL de notification 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.