Inscrire un webhook

Utilisez le plug-in Outil d’inscription pour inscrire un webhook. Pour obtenir l’outil Plug-in Registration Tool, voir Outils de développement Dataverse.

Dans l’outil Plug-in Registration Tool, sélectionnez l’option Inscrire nouveau webhook.

Lorsque vous inscrivez un webhook, vous devez fournir trois informations :

Item	Description
Nom	Un nom unique décrivant le webhook.
une URL de point de terminaison	L’URL sur laquelle publier les informations du contexte d’exécution.
Authentification	Une des trois options d’authentification. Pour chaque type d’authentification, vous devez fournir les clés qui identifient la requête comme légitime.

Les WebHooks enregistrés prennent uniquement en charge le port 80 pour HTTP et le port 443 pour HTTPS.

Options d’authentification

L’option et les valeurs correctes d’authentification de l’inscription du webhook dépendent des attentes du point de terminaison. Le propriétaire du point de terminaison doit vous indiquer qu’utiliser. Pour utiliser des webhooks avec Microsoft Dataverse, le point de terminaison doit autoriser une des options d’authentification suivantes :

Type	Description
HttpHeader	comprend une ou plusieurs paires clé-valeur dans l’en-tête de la requête HTTP. Exemple : Key1: Value1 Key2: Value2
WebhookKey	Inclut une chaîne de requête utilisant code comme clé et une valeur requise par le point de terminaison. Lorsque vous enregistrez le webhook à l’aide de l’outil Plug-in Registration, entrez uniquement la valeur. Exemple : ?code=00000000-0000-0000-0000-000000000001
HttpQueryString	comprend une ou plusieurs paires clé-valeur comme paramètres de chaîne de requête. Exemple : ?Key1=Value1&Key2=Value2

Notes

L’option WebhookKey est utile avec les Fonctions Azure car la chaîne de requête d’authentification doit comporter un nom de clé code.

Une requête adressée au point de terminaison configuré doit échouer lorsque les options d’authentification passées dans la requête ne correspondent pas. Le point de terminaison en est responsable.

Inscriptions de webhook de requête

Les inscriptions de webhook sont stockées dans la table ServiceEndpoint et ont une valeur Contrat de 8.

Vous pouvez obtenir des détails sur les webhooks inscrits en interrogeant la table ServiceEndpoint.

API Web :

GET [organization URI]/api/data/v9.0/serviceendpoints?$filter=contract eq 8&$select= serviceendpointid,name,authtype,url

Plus d’informations : Interroger les données à l’aide de l’API Web

FetchXml:

<fetch>
  <entity name="serviceendpoint" >
    <attribute name="serviceendpointid" />
    <attribute name="name" />
    <attribute name="authtype" />
    <attribute name="url" />
    <filter>
      <condition attribute="contract" operator="eq" value="8" />
    </filter>
  </entity>
</fetch> 

Plus d’informations : Utiliser FetchXML pour récupérer des données

Les détails des valeurs d’authentification définies se trouvent dans la propriété AuthValue et ne sont pas récupérables.

Inscrire une étape pour un webhook

Inscrire une étape pour un webhook est semblable à inscrire une étape pour un plug-in. La principale différence est qu’il est impossible de spécifier des informations de configuration.

Comme un plug-in, vous spécifiez le message et les informations sur les tables le cas échéant. Vous pouvez également spécifier où exécuter webhook dans le pipeline d’événement, le mode d’exécution et s’il faut supprimer les objets AsyncOperation lorsque l’opération aboutit.

Les informations sur le Nom de l’étape et la Description sont remplies automatiquement en fonction des options choisies, mais vous pouvez les modifier. Si vous ne définissez pas d’Attribut de filtrage pour un message qui les prend en charge, vous êtes invité à le faire dans le cadre des meilleures pratiques de performance.

Mode d’exécution et débogage de votre inscription de webhook

Votre choix d’inscription de webhook modifie votre expérience au moment du débogage si tout ne fonctionne pas bien.

Mode Asynchrone

Lorsque vous utilisez le mode d’exécution asynchrone, une tâche système (opération asynchrone) est créée pour capturer la réussite ou l’échec de l’opération. Choisir de supprimer la tâche système quand elle aboutit vous fait économiser de l’espace de base de données.

Toutes les erreurs qui se produisent sont enregistrées dans les tâches système. Dans l’application web vous pouvez accéder à Paramètres > Système > Tâches système pour afficher l’état de tous les webhooks. Il s’y trouve une valeur de Raison du statut Échec. Ouvrez l’entité de la tâche système en échec pour voir les détails qui décrivent pourquoi la tâche a échoué.

Tâches asynchrones de requête échouées pour une étape donnée

Lorsque vous connaissez sdkmessageprocessingstepid d’une étape donnée, vous pouvez interroger la Table AsynchronousOperations sur toutes les erreurs. Vous pouvez utiliser la valeur OwningExtensionId pour filtrer les résultats pour une étape inscrite particulière. Les exemples suivants utilisent le <stepid> pour le sdkmessageprocessingstepid de l’étape.

Conseil

Pour obtenir le sdkmessageprocessingstepid d’une étape donnée, voir Étapes de requêtes inscrites pour un webhook ci-dessous.

API Web :

GET [organization URI]/api/data/v9.0/asyncoperations?$orderby=completedon desc&$filter=statuscode eq 31 and _owningextensionid_value eq @stepid&$select=name,friendlymessage,errorcode,message,completedon?@stepid=<stepid>

Plus d’informations : Interroger les données à l’aide de l’API Web

FetchXML:

<fetch>
  <entity name="asyncoperation" >
    <attribute name="name" />
        <attribute name="friendlymessage" />
    <attribute name="errorcode" />
    <attribute name="message" />
    <attribute name="completedon" />     
    <filter>
      <condition attribute="owningextensionid" operator="eq" value="<stepid>" />
    </filter>
    <order attribute="completedon" descending="true" />
  </entity>
</fetch>

Plus d’informations : Utiliser FetchXML pour récupérer des données

Mode synchrone

Lorsque vous choisissez d’utiliser un mode d’exécution synchrone, toute défaillance est signalée à l’utilisateur de l’application par une boîte de dialogue d’erreur Point de terminaison non disponible informant l’utilisateur que le point de terminaison du service de webhook peut être configuré incorrectement ou n’est pas disponible. Cette boîte de dialogue vous permet de télécharger un fichier journal pour avoir des détails sur les erreurs.

Notes

Vous devez utiliser le mode synchrone lorsqu’il est important que l’opération déclenchée par le webhook se produise immédiatement ,ou si vous souhaitez que la transaction entière échoue si la charge utile du webhook n’est pas reçue par le service. L’inscription simple d’une étape webhook fournit des options limitées pour gérer les échecs, mais vous pouvez également appeler des webhooks en utilisant des plug-ins et des activités de workflow s’il vous faut davantage de contrôle. Informations complémentaires : Appeler un webhook à partir d’un plug-in ou d’une activité de workflow.

Étapes de requêtes inscrites pour un webhook

Les données des webhooks inscrits sont dans la Table SdkMessageProcessingStep.

Vous pouvez interroger les étapes inscrites pour un webhook spécifique lorsque vous connaissez le serviceendpointid du webhook. Voir Inscriptions de webhook de requête pour une requête d’obtention de l’ID d’un webhook inscrit.

API Web :

Vous pouvez utiliser cette requête d’API Web où <id> est le ServiceEndpointId du webhook :

GET [organization URI]/api/data/v9.0/serviceendpoints(@id)/serviceendpoint_sdkmessageprocessingstep?$select=sdkmessageprocessingstepid,name,description,asyncautodelete,filteringattributes,mode,stage?@id=<id>

Pour plus d’informations sur l’étape inscrite, vous pouvez utiliser cette requête d’API Web où <stepid> est le SdkMessageProcessingStepId de l’étape :

GET [organization URI]/api/data/v9.0/sdkmessageprocessingsteps(@id)?$select=name,description,filteringattributes,asyncautodelete,mode,stage&$expand=plugintypeid($select=friendlyname),eventhandler_serviceendpoint($select=name),sdkmessagefilterid($select=primaryobjecttypecode),sdkmessageid($select=name)?@id=<stepid>

FetchXML:

Vous pouvez utiliser ce FetchXML pour obtenir les mêmes informations en une requête où <serviceendpointid> représente l’ID du webhook :

<fetch>
  <entity name="sdkmessageprocessingstep" >
    <attribute name="name" />
    <attribute name="filteringattributes" />
    <attribute name="stage" />
    <attribute name="asyncautodeletename" />
    <attribute name="description" />
    <attribute name="mode" />
    <link-entity name="serviceendpoint" from="serviceendpointid" to="eventhandler" link-type="inner" alias="endpnt" >
      <attribute name="name" />
      <filter>
        <condition attribute="serviceendpointid" operator="eq" value="<serviceendpointid>" />
      </filter>
    </link-entity>
    <link-entity name="sdkmessagefilter" from="sdkmessagefilterid" to="sdkmessagefilterid" link-type="inner" alias="fltr" >
      <attribute name="primaryobjecttypecode" />
    </link-entity>
    <link-entity name="sdkmessage" from="sdkmessageid" to="sdkmessageid" link-type="inner" alias="msg" >
      <attribute name="name" />
    </link-entity>
  </entity>
</fetch>

Étapes suivantes

Tester l’inscription du webhook avec un site de journalisation des requêtes
Utiliser des webhooks pour créer des gestionnaires externes pour les événements de serveur

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).