Webhook

Imaginez que vous gérez une boutique de vêtements en ligne. Chaque fois que vous enregistrez un nouveau produit, il y a des tâches annexes dont vous devez vous occuper vous-même : traduire la description du produit dans une autre langue, ou prévenir l'arrivée de ce produit sur la messagerie interne de l'entreprise, par exemple. Plutôt que de faire ces tâches annexes à la main à chaque fois, vous pouvez prévenir automatiquement un programme externe au moment où un produit est enregistré, pour qu'il s'en charge à votre place. Ce « dispositif qui prévient automatiquement un endroit défini à l'avance lorsqu'un événement se produit » est le Webhook.

On peut le comparer à la sonnette installée à la porte d'une boutique. Lorsqu'un client ouvre la porte et entre (lorsqu'un produit est enregistré), la sonnette retentit d'elle-même, et l'employé à l'intérieur (le programme externe) se dit « un client est arrivé » et se met aussitôt en mouvement. Personne n'a besoin de surveiller la porte en permanence. Le Webhook, comme cette sonnette, démarre automatiquement une action définie à l'instant où l'événement défini se produit.

Cette page commence par examiner ce qu'est un Webhook et dans quels cas l'utiliser, puis vous créez vous-même un Webhook dans le Space de la boutique de vêtements.

Ce que fait le Webhook

Un Webhook se compose de trois choses à définir à l'avance.

• Quand : vous définissez à la suite de quel événement il réagit. Par exemple, vous pouvez choisir « lorsqu'un produit (Content) est nouvellement enregistré ».
• Que faire : vous définissez l'une des deux options. Soit envoyer une requête à l'adresse Internet (URL) d'un programme externe, soit exécuter un Script créé au sein du Space.
• Activé ou désactivé : vous définissez si ce Webhook est actif maintenant (Active) ou momentanément désactivé (Inactive). S'il est désactivé, rien ne se produit même lorsque l'événement défini se produit.

Lorsque l'événement défini se produit réellement, le Webhook accomplit l'action définie. Lorsqu'il envoie vers une adresse externe, la requête emporte des informations comme la nature de l'événement et le produit dans lequel il s'est produit. Le programme externe qui reçoit la requête consulte ces informations et accomplit sa propre tâche.

À quels changements une requête est-elle envoyée

L'« événement » qui déclenche une requête est un changement survenant sur une ressource au sein du Space. Vous pouvez choisir le moment où quelque chose se produit sur un Content comme un produit, sur un Media qui est un fichier téléversé, ou sur un Content Type qui est un modèle de formulaire.

Les changements que vous pouvez choisir varient selon la ressource.

Par exemple, « envoyer une requête chaque fois qu'un produit est nouvellement enregistré » revient à choisir le Create du produit (Content).

Vous pouvez aussi choisir plusieurs changements à la fois dans un même Webhook. Si vous choisissez à la fois « lorsqu'un produit est enregistré » et « lorsqu'un produit est modifié », la requête part quel que soit celui des deux qui se produit.

Restreindre avec des conditions

Il arrive que vous ne vouliez pas envoyer une requête chaque fois que le changement choisi se produit. Par exemple, vous pouvez vouloir la recevoir « non pas pour tout Content, mais seulement lorsqu'un Content créé avec le formulaire « produit » est enregistré ». Dans ce cas, vous restreignez les cas d'envoi en posant un filtre.

Un filtre se compose d'une ligne indiquant « sur quel critère et comment comparer ». Le critère de filtrage se choisit parmi quatre options.

• Avec quel formulaire l'élément a été créé : par exemple, n'envoyer une requête que pour les Content créés avec le Content Type « produit ». C'est la condition la plus fréquemment utilisée.
• S'il s'agit d'un élément précis : n'envoyer une requête que pour les changements survenus sur cet élément précis défini.
• Par qui l'élément a été créé : n'envoyer une requête que pour les éléments créés par une personne précise.
• Par qui l'élément a été modifié en dernier : n'envoyer une requête que pour les éléments modifiés en dernier par une personne précise.

Vous choisissez aussi le mode de comparaison. Vous pouvez restreindre aux cas où la valeur est égale à la valeur définie, où elle en diffère, où elle correspond à l'une de plusieurs valeurs définies, où elle ne correspond à aucune d'entre elles, ou encore où elle correspond ou non à un format (motif) défini.

Dans le réglage du déclencheur du studio de contenu, vous ajoutez les conditions une ligne à la fois avec Ajouter Un Filtre. Si vous posez plusieurs filtres, la requête ne part que lorsque toutes ces conditions sont satisfaites ; si vous n'en posez aucune, la requête part chaque fois que le changement choisi se produit.

Envoyer dans la forme attendue par le programme externe

Si vous ne définissez rien de particulier, la requête emporte l'intégralité des informations de l'élément où le changement s'est produit. Par exemple, lorsque le produit gobelet est enregistré, le contenu emporté par la requête a à peu près cette forme.

{
  "sys": { "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq", "type": "Content" },
  "fields": {
    "productName": { "ko-KR": "스테인리스 텀블러 500ml" }
  }
}

(En réalité, davantage d'informations y figurent ; ce qui précède n'est qu'un extrait.) Le programme externe n'a qu'à y prélever les valeurs dont il a besoin. Mais certains programmes imposent un format : « je ne recevrai que sous cette forme ». Dans ce cas, dans le Charge utile du studio de contenu, choisissez Personnaliser la charge utile du Webhook et inscrivez vous-même la forme à envoyer.

Inscrivez la forme à envoyer, mais aux emplacements où vous voulez insérer une valeur tirée des données ci-dessus, utilisez un espace réservé. L'espace réservé a la forme { /payload/… }. Ici, payload désigne l'élément complet montré plus haut, et le chemin qui suit pointe précisément sur la valeur souhaitée.

• { /payload/sys/id } → le id dans le sys des données ci-dessus (le numéro unique du produit)
• { /payload/fields/productName/ko-KR } → le ko-KR du productName dans fields (le nom de produit en coréen). Après fields/, ajoutez successivement l'ID du Field (productName pour le nom de produit) et le code de langue (ko-KR pour le coréen).

Par exemple, si le programme de traduction demande « donne-moi le texte à traduire et le numéro de produit sous cette forme », inscrivez le payload ainsi.

{
  "id": "{ /payload/sys/id }",
  "text": "{ /payload/fields/productName/ko-KR }"
}

Alors, à l'instant où le produit gobelet est enregistré, les espaces réservés sont remplacés par les valeurs réelles et transmis ainsi.

{
  "id": "3trmXRM3RqbgSnifyg7OGhwhlqvAvq",
  "text": "스테인리스 텀블러 500ml"
}

Le même espace réservé peut aussi être inséré dans l'adresse d'envoi (URL) ou dans la valeur d'un en-tête, et vous pouvez aussi choisir le mode d'envoi (method) et le format (JSON ou format de formulaire). Si aucune valeur ne se trouve au chemin pointé, cet emplacement devient une valeur vide.

Pour les valeurs qui ne doivent pas être visibles par autrui, comme une clé d'API externe, lors de l'ajout de l'en-tête, définissez son type sur Secret. La valeur est alors masquée à l'enregistrement et n'est pas exposée à l'utilisateur final.

Exécuter un Script au lieu d'une URL

Jusqu'à présent, le Webhook envoyait une requête vers une adresse externe (URL). À la place, un Webhook peut exécuter un Script créé au sein du Space. Un Script est un dispositif qui accomplit au sein du Space, sans en sortir, les tâches que vous avez définies (créer et modifier des ressources, etc.). Vous utilisez cette approche lorsque vous voulez terminer les tâches annexes au sein du Space sans passer par un programme externe.

Un seul Webhook fait exactement l'une des deux choses : envoyer vers une adresse externe, ou exécuter un Script. Cela se définit dans Cible de la requête sur l'écran de création. Si vous choisissez Saisir une URL, la requête part vers l'adresse comme précédemment ; si, à la place, vous choisissez un Script dans la liste, c'est ce Script qui est exécuté.

Lorsque vous choisissez un Script, apparaît aussi Run as, qui définit sous quelle identité ce Script s'exécute. Vous en choisissez l'une des deux.

• Créateur du Webhook (par défaut) : le « créateur » de toute ressource créée ou modifiée pendant l'exécution est enregistré comme la personne qui a créé le Webhook.
• Utilisateur déclencheur : il est enregistré comme l'utilisateur qui a provoqué ce changement.

Ce réglage ne fait que déterminer la marque « qui l'a fait » laissée sur les ressources ; il n'élargit ni ne restreint ce que le Script peut faire. L'étendue de ce qu'un Script peut faire est déjà définie au moment où vous le créez.

Concrètement, la sélection se déroule dans l'ordre suivant.

1. Sur l'écran de création, cliquez sur Cible de la requête.
2. Choisissez dans la liste le Script à exécuter. Vous choisissez un Script au lieu de Saisir une URL.
3. Dans Run as, choisissez l'identité. Par défaut, c'est Créateur du Webhook.

Ce qu'est un Script et comment en créer un est abordé dans Script.

Créer un Webhook pour la boutique de vêtements

Vous allez maintenant créer un Webhook dans le Space de la boutique de vêtements. C'est un Webhook qui « prévient un programme de traduction externe préparé à l'avance lorsqu'un nouveau produit est enregistré ». Disons que l'adresse du programme externe qui recevra la requête est https://example.com/translate.

1. Dans les réglages du Space de la boutique de vêtements, ouvrez l'écran Webhook.
2. Appuyez sur le bouton Créer en haut à droite.
3. Saisissez Notification de traduction de nouveau produit dans le champ du nom. Ce nom sert ensuite à reconnaître de quel Webhook il s'agit.
4. Définissez le changement qui enverra la requête. Pour n'envoyer que pour un changement précis, choisissez Sélectionner des événements déclencheurs spécifiques puis spécifiez le changement souhaité (ici, le Create du produit (Content)) ; pour envoyer à chaque changement, choisissez Déclencher pour tous les événements.
5. Saisissez dans le champ URL l'adresse https://example.com/translate du programme externe qui recevra la requête.
6. Si vous activez Actif, la requête est envoyée dès la création (Active). Pour seulement faire un essai momentané, laissez-le désactivé (Inactive).
7. Appuyez sur le bouton Créer pour créer le Webhook.

Lorsque Notification de traduction de nouveau produit apparaît dans la liste à l'état Active, c'est que le Webhook a été créé.

Après la création, enregistrez réellement un nouveau produit dans la boutique. À l'instant de l'enregistrement, le Webhook envoie une requête à l'adresse inscrite. Vous pouvez vérifier si la requête est bien partie et comment le programme externe a répondu dans l'historique des appels du Webhook.

Activer, désactiver et modifier

Un Webhook peut être activé et désactivé à tout moment après sa création. Lorsque vous voulez suspendre momentanément les requêtes, ne le supprimez pas, mais désactivez-le en Inactive. Pendant qu'il est désactivé, aucune requête ne part même si vous enregistrez un nouveau produit. Si vous le réactivez en Active, il recommence dès lors à envoyer des requêtes.

Si vous rouvrez un Webhook créé, vous pouvez désactiver Actif ou le réactiver. Vous pouvez aussi modifier ensuite des éléments comme le nom, l'adresse d'envoi de la requête et le changement à capter ; et un Webhook que vous n'utilisez plus, vous n'avez qu'à le supprimer.

Et ensuite

• Modélisation du Content : aborde la manière de créer le modèle de formulaire d'un Content comme le « produit », sur lequel le Webhook déclenche ses requêtes.
• Créer et publier un Content : vous pouvez enregistrer un vrai produit et vérifier que le Webhook fonctionne.
• Script : aborde la manière de créer le travail qui s'exécute au sein du Space, que le Webhook peut exécuter au lieu d'une URL.
• Référence de l'API : aborde les formats de requête et de réponse ainsi que les spécifications des champs utilisés pour créer et gérer un Webhook directement depuis un programme.