Déclencheur de webhook
Les webhooks sont des implémentations HTTP plébiscités, d’un type de notification éditeur-abonné plus générique. Ils permettent de délivrer des notifications à un service externe (abonné) chaque fois que certains événements se produisent au sein d’un système (éditeur).
Power Automate et Azure Logic Apps permettent aux créateurs d’utiliser des webhooks comme déclencheurs. Dans ce cas, les déclencheurs jouent le rôle d’un abonné qui inscrit et désinscrit des webhooks pour le compte d’un créateur. L’inscription se produit lorsqu’une étape d’un flux de cloud ou d’un flux de travail Logic Apps est créée ou mise à jour. Lorsque l’étape est supprimée, la plateforme désinscrit le webhook.
Comme Copilot peut vous aider à configurer votre connecteur, il peut également vous aider ici aussi. Vous pouvez commencer avec des invites simples et, au fur et à mesure de votre progression, améliorer votre implémentation :
« Comment définir un déclencheur HTTP pour mon connecteur personnalisé ? »
« Quels paramètres dois-je inclure dans mon déclencheur de connecteur personnalisé ? »
« Pouvez-vous vérifier ma logique de déclencheur pour des améliorations potentielles ? »
Copilot peut suggérer la manière optimale de définir les déclencheurs en fonction de votre API et des exigences du flux.
La capture d’écran suivante montre un exemple de l’interaction entre l’abonné et l’éditeur :
Les responsabilités des deux parties sont présentées dans le tableau suivant.
| Éditeur (connecteur personnalisé OpenAPI) | Abonné (Power Automate/Logic Apps) |
|---|---|
| Indique le point de terminaison de l’inscription de l’abonnement. | Appelle le point de terminaison d’inscription de l’abonnement lorsqu’un déclencheur est créé ou mis à jour dans un flux. |
| Désigne le contrat de notification, à savoir, l’objet qui sera transmis avec chaque notification. Doit inclure l’en-tête HTTP d’emplacement dans la réponse 201 au moment de la création d’un webhook. | Précise l’URL du point de terminaison généré automatiquement qui acceptera les messages de notification. |
| Tient à jour le registre des abonnés et leurs points de terminaison de notification. | Reçoit et stocke les informations de localisation qui seront utilisées pour désinscrire le webhook. |
| Envoie une requête POST à chaque point de terminaison inscrit et transmet les données pertinentes dans le corps du message. | Reçoit les notifications, les valide par rapport au schéma défini par le connecteur personnalisé, puis déclenche l’automatisation. |
| Désinscrit ou supprime les points de terminaison en réponse au message DELETE. | Émet un message DELETE pour désinscrire le webhook lorsque l’étape de déclenchement est supprimée. |
Les webhooks fournissent uniquement le mécanisme de notification ; ils ne prennent pas en charge le traitement des données. Souvent, une implémentation de webhook est complétée par une ou plusieurs actions conçues pour prendre en charge la récupération et la manipulation de données ou d’objets.
Exigences relatives à l’API
Afin de permettre la prise en charge de webhooks dont ont besoin les connecteurs personnalisés, l’implémentation de l’API doit fournir les paramètres suivants :
Un point de terminaison qui accepte le message d’inscription et renvoie des informations de localisation
Une définition du corps du message envoyée avec les messages de notification
Un point de terminaison pour accepter le message DELETE destiné à supprimer l’inscription du webhook
Habituellement, l’implémentation de l’API gère une liste interne d’abonnés actifs, dans laquelle chaque abonné est identifié par une URL unique. Pour retourner cette URL à l’abonné, la création du webhook doit aboutir afin de renvoyer une réponse HTTP 201 comprenant un en-tête HTTP Location. La valeur de cet emplacement sera utilisée ultérieurement par l’abonné pour supprimer l’inscription du webhook.
Créer un déclencheur de webhook
OpenAPI permet aux connecteurs personnalisés de décrire l’implémentation de l’API de l’éditeur, comme requis par les webhooks. Pour définir un déclencheur de webhook dans un connecteur personnalisé, vous devez inclure trois éléments clés dans la définition OpenAPI :
Un message POST qui décrit l’inscription du webhook
Une définition de contenu pour les réponses du webhook
Un message DELETE qui décrit le processus de suppression du webhook
Message d’inscription
La définition du déclencheur doit inclure une méthode POST qui permet d’inscrire un webhook. Elle est définie de la même manière que les actions.
La version de la spécification OpenAPI utilisée par Microsoft Power Platform ne différencie pas les actions et les déclencheurs. La définition de connecteur personnalisé utilise l’extension personnalisée x-ms-trigger pour déclarer un déclencheur.
paths:
/webhooks:
post:
operationId: OrderCreated
x-ms-trigger: single
La présence de l’extension x-ms-trigger indique que la méthode est un déclencheur et non une action. Lorsqu’un déclencheur est créé avec l’assistant, cette extension est ajoutée automatiquement. Cependant, lorsqu’un connecteur personnalisé est créé à partir des définitions OpenAPI externes, le processus d’importation crée toujours des actions. Dans ce cas, vous devez recréer les déclencheurs à l’aide de l’Assistant, puis supprimer les définitions d’action correspondantes.
Les valeurs possibles pour le déclencheur x-ms-trigger sont unique ou lot, afin de faire la distinction entre les réponses d’un objet et d’un tableau. Un objet unique est inclus lorsqu’un webhook déclenche une notification pour chaque modification. Cette approche est la plus courante avec les webhooks. Lorsque plusieurs modifications sont combinées en une seule notification, un tableau d’objets est envoyé. Cette approche est généralement utilisée dans les déclencheurs d’interrogation et nous la verrons plus loin dans ce module.
Réponse du webhook
Les définitions de connecteur personnalisés peuvent décrire le contenu des réponses de webhook entrantes de votre service lorsqu’un événement se produit. Bien qu’elle ne soit pas obligatoire, cette définition identifie les valeurs dynamiques disponibles dans la liste de contenu dynamique pour le créateur au moment de la conception.
Remarque
Cette réponse ne fait pas partie de la requête qui crée et inscrit le webhook. Ces données sont envoyées par votre service lorsqu’un événement survient.
La propriété personnalisée x-ms-notification-content est une autre extension permettant de définir le schéma de réponse du webhook dans OpenAPI.
paths:
/webhooks:
x-ms-notification-content:
description: Order
schema:
type: object
properties:
id: {type: integer, format: int32, description: id}
order_key: {type: string, description: order_key}
status: {type: string, description: status}
currency: {type: string, description: currency}
date_created: {type: string, description: date_created}
total: {type: number, description: total, format: decimal}
Conseil
Une définition de réponse de webhook n’a pas besoin de contenir l’intégralité du contenu de la réponse, uniquement les parties que vous souhaitez présenter dans la liste de contenu dynamique aux créateurs de flux au moment de la conception.
Les données envoyées avec la réponse du webhook n’ont pas besoin de toutes les propriétés dont vous avez besoin de la part de l’objet sous-jacent et peuvent ne pas les contenir. Dans ces cas, vous pouvez créer d’autres actions dans le connecteur personnalisé pour récupérer les informations. Par exemple, une boutique en ligne peut uniquement envoyer un nouveau numéro de commande avec la notification « Quand une commande est créée ». Ensuite, le connecteur personnalisé peut définir une action, par exemple, « Obtenir les détails de la commande », qui accepte un numéro de commande et renvoie des informations détaillées concernant la commande.
L’inverse est également vrai. Les réponses de webhook peuvent fournir trop d’informations, superflues ou non indispensables dans des circonstances normales. Il vous suffit de décrire les données que vous souhaitez afficher dans Power Automate ou l’interface des créateurs Logic Apps. Si le créateur a besoin d’accéder à plus de données envoyées dans la notification, il peut utiliser les fonctions JSON pour extraire directement ces propriétés du message reçu.
Supprimer le message
Pour que Power Automate ou Logic Apps supprime un webhook, l’API doit inclure un en-tête HTTP Location dans la réponse au moment de la création du webhook.
Important
Vous devez définir le chemin de la demande de suppression du webhook en tant qu’action interne. Cette action envoie une requête DELETE à l’URL spécifiée dans l’en-tête d’emplacement.
Si cette action n’est pas définie ou si l’API ne comprend pas l’en-tête d’emplacement, les webhooks sont créés mais ils ne sont pas supprimés, ce qui pourrait entraîner des problèmes d’implémentation de l’API au moment de l’exécution.
L’implémentation des webhooks offre un mécanisme flexible pour la prise en charge des déclencheurs dans un connecteur personnalisé. Cependant, les API ne prennent pas toutes en charge les intégrations de webhook. L’implémentation de l’interrogation constitue un autre moyen de créer des déclencheurs dans les connecteurs personnalisés.