Présentation des webhooks SharePoint

Article
04/08/2023

Les webhooks SharePoint permettent aux développeurs de créer des applications qui s’abonnent pour recevoir des notifications sur des événements spécifiques qui se produisent dans SharePoint. Lorsqu’un événement est déclenché, SharePoint envoie une charge utile HTTP POST à l’abonné. Les webhooks sont plus faciles à développer et à consommer que les services Windows Communication Foundation (WCF) utilisés par les récepteurs d’événements distants des compléments SharePoint, car les webhooks sont des services HTTP normaux (API web).

Actuellement, les webhooks sont activés uniquement pour les éléments de liste SharePoint. Les webhooks d’éléments de liste SharePoint couvrent les événements qui correspondent à des modifications d’éléments de liste pour une liste ou une bibliothèque de documents SharePoint donnée. Les webhooks SharePoint fournissent un pipeline de notification simple grâce auquel votre application peut être informée des modifications apportées à une liste SharePoint sans avoir à interroger le service. Pour plus d’informations, consultez la rubrique Webhooks de liste SharePoint.

Création de webhooks

Pour créer un webhook SharePoint, vous devez ajouter un nouvel abonnement à la ressource SharePoint spécifique, par exemple une liste SharePoint.

Les informations suivantes sont requises pour la création d’un abonnement :

Ressource. URL du point de terminaison de ressource pour laquelle vous créez l’abonnement. Par exemple, une URL d’API de liste SharePoint.
URL de notification du serveur. URL de votre point de terminaison de service. SharePoint envoie une demande HTTP POST à ce point de terminaison en cas d’événements sur la ressource spécifiée.
Date d’expiration. Date d’expiration de votre abonnement. La date d’expiration ne doit pas dépasser 180 jours. Par défaut, les abonnements sont configurés pour expirer 180 jours après leur création.

Vous pouvez également inclure les informations suivantes si nécessaire :

État du client. Chaîne opaque renvoyée au client pour toutes les notifications. Vous pouvez utiliser cette chaîne pour valider les notifications, marquer différents abonnements ou pour d’autres raisons.

Gestion des demandes de validation de webhooks

Lorsqu’un nouvel abonnement est créé, SharePoint vérifie que l’URL de notification prend en charge la réception de notifications par webhook. Ce contrôle est réalisé lors de la demande de création d’abonnement. L’abonnement n’est créé que si votre service répond en temps voulu avec le jeton de validation.

Exemple de demande de validation

Lorsqu’un nouvel abonnement est créé, SharePoint envoie une demande HTTP POST à l’URL inscrite dans un format semblable au suivant :

POST https://contoso.azurewebsites.net/your/webhook/service?validationtoken={randomString}
Content-Length: 0

Réponse

Pour que l’abonnement soit créé correctement, votre service doit répondre à la demande en renvoyant la valeur du paramètre de chaîne de demande validationtoken en tant que réponse au format texte brut.

HTTP/1.1 200 OK
Content-Type: text/plain

{randomString}

Si votre application renvoie un code d’état autre que 200 ou ne répond pas avec la valeur du paramètre validationtoken, la demande de création d’abonnement échoue.

Réception des notifications

La charge utile de notification informe votre application qu’un événement s’est produit dans une ressource donnée pour un abonnement donné. Si plusieurs modifications sont apportées à la ressource sur la même période, les différentes notifications envoyées à votre application peuvent être regroupées en une seule demande.

Le corps de la charge utile de notification contient également l’état de votre client si vous l’utilisiez lors de la création de l’abonnement.

Ressource de notification webhook

La ressource de notification définit la forme des données fournies dans votre service lorsqu’une demande de notification webhook SharePoint est soumise à l’URL de notification enregistrée.

Représentation JSON

Chaque notification générée par le service est sérialisée dans une instance webhookNotification :

{
    "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
    "clientState":"00000000-0000-0000-0000-000000000000",
    "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
    "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
    "tenantId":"00000000-0000-0000-0000-000000000000",
    "siteUrl":"/",
    "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
}

Étant donné que plusieurs notifications peuvent être envoyées à votre service au sein d’une même demande, elles sont combinées dans un objet avec une seule valeur collective.

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

Propriétés

Nom de la propriété	Type	Description
resource	String	Identificateur unique de la liste où l’abonnement est inscrit.
subscriptionId	String	Identificateur unique pour la ressource faisant l’objet de l’abonnement.
clientState	Chaîne - facultatif	Valeur de chaîne facultative qui est renvoyée dans le message de notification de cet abonnement.
expirationDateTime	DateTime	Date et heure d’expiration de l’abonnement s’il n’est pas mis à jour ou renouvelé.
tenantId	String	Identificateur unique pour le client ayant généré cette notification.
siteUrl	String	URL relative du serveur du site où l’abonnement est inscrit.
webId	String	Identificateur unique du site web où l’abonnement est inscrit.

Exemple de notification

Le corps de la requête HTTP adressée à l’URL de votre service de notification contient une notification webhook. L’exemple suivant montre une charge utile avec une notification :

{
   "value":[
      {
         "subscriptionId":"91779246-afe9-4525-b122-6c199ae89211",
         "clientState":"00000000-0000-0000-0000-000000000000",
         "expirationDateTime":"2016-04-30T17:27:00.0000000Z",
         "resource":"b9f6f714-9df8-470b-b22e-653855e1c181",
         "tenantId":"00000000-0000-0000-0000-000000000000",
         "siteUrl":"/",
         "webId":"dbc5a806-e4d4-46e5-951c-6344d70b62fa"
      }
   ]
}

La notification n’inclut pas d’informations sur les modifications qui l’ont déclenchée. Votre application utilise normalement l’API GetChanges sur la liste pour rechercher l’ensemble des modifications dans le journal des modifications et stocker la valeur de jeton de modification pour les appels ultérieurs lorsque l’application reçoit la notification.

Types d’événements

Les webhooks SharePoint prennent uniquement en charge les événements asynchrones. Cela signifie qu’ils sont déclenchés uniquement après une modification (semblable aux événements -ed) et que les événements synchrones (événements -ing) ne sont pas possibles.

Gestion des erreurs

Si une erreur se produit lors de l’envoi de la notification à votre application, SharePoint réessaye de vous renvoyer la notification à 5 reprises. Toute demande dont la réponse a un code de statut HTTP en dehors de la plage 200-299 ou qui arrive à expiration est réessayée 5 minutes plus tard. Si la demande n’aboutit pas après 5 tentatives, la notification est abandonnée. Les notifications ultérieures feront tout de même l’objet d’une tentative d’envoi à votre application.

Expiration

Par défaut, les abonnements webhook ont un délai d’expiration de 180 jours si aucune valeur expirationDateTime n’est spécifiée.

Vous devez définir une date d’expiration lorsque vous créez l’abonnement. La date d’expiration doit être inférieure à 180 jours. Votre application gère normalement l’expiration en fonction de ses besoins, en mettant à jour l’abonnement régulièrement.

Nouvelles tentatives

Si un événement se produit dans SharePoint et que le point de terminaison de votre service n’est pas accessible (par exemple, pour des raisons de maintenance) SharePoint réessaie d’envoyer la notification. SharePoint effectue cinq tentatives à intervalles de cinq minutes. Si, pour une raison quelconque, votre service est arrêté pour une période plus longue, puis réactivé, lors du premier appel par SharePoint, l’appel de GetChanges() récupère les modifications manquées lorsque votre service n’était pas disponible.

Partager via