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, envoie une requête vers un endroit défini à 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. Elle aborde aussi le WriteBack, qui réinsère dans le produit le résultat renvoyé par le programme externe.

Ce que fait le Webhook

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

• Quand envoyer : vous définissez à la suite de quel événement la requête est envoyée. Par exemple, vous pouvez choisir « lorsqu'un produit (Content) est nouvellement enregistré ».
• Où envoyer : vous définissez l'adresse du programme externe qui recevra la requête. Vous y inscrivez une adresse Internet (URL).
• 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é, aucune requête n'est envoyée même lorsque l'événement défini se produit.

Lorsque l'événement défini se produit réellement, le Webhook envoie à l'adresse inscrite une requête signalant ce fait. La requête contient 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 toujours envoyer une requête simplement parce que le changement choisi s'est 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.

Réinsérer à partir de la réponse reçue : WriteBack

Si la section précédente définit la forme de la requête envoyée, le WriteBack traite la réponse qui revient. Lorsque le Webhook appelle le programme externe et reçoit une réponse normale (2xx), il peut traiter cette réponse pour créer, modifier, publier ou supprimer un Content ou un Media au sein du Space. Le processus consistant à copier-coller le résultat à la main disparaît.

Suivons jusqu'au bout l'exemple de traduction de la boutique de vêtements. Précédemment, le nom de produit en coréen du nouveau produit a été envoyé au programme de traduction. Supposons que le programme de traduction réponde ainsi.

{ "translated": "Stainless Tumbler 500ml" }

Vous configurez un WriteBack qui place ce texte traduit dans le champ du nom de produit en anglais du même produit. Dans le WriteBack du studio de contenu, ajoutez une action Update (modification) de Content avec Ajouter Une Opération et définissez-la ainsi.

• Cible : si vous ne définissez rien de particulier, le produit où le changement s'est produit (le gobelet) devient la cible.
• Champ et langue à remplir : comme il s'agit du nom de produit en anglais, le champ est le nom de produit (productName) et la langue est l'anglais (en-US).
• Valeur à insérer : { /response/translated }, qui pointe sur le texte traduit de la réponse.

Le champ du nom de produit en anglais du produit gobelet est alors rempli avec Stainless Tumbler 500ml.

Un tel WriteBack est particulièrement utile pour faire le lien avec un LLM externe. Par exemple, vous pouvez composer avec un seul Webhook un flux qui enregistre comme Media une image promotionnelle créée à partir de la description d'un produit, ou qui crée un nouveau Content à partir d'un texte de présentation généré.

Ordre d'exécution

1. Lorsqu'un changement se produit, le Webhook envoie une requête au programme externe dans la forme définie.
2. Si la réponse est 2xx, les actions de WriteBack ajoutées sont exécutées dans l'ordre, de haut en bas.
3. Chaque action étant indépendante, même si l'une échoue, les autres continuent de s'exécuter.
4. Les créations, modifications, suppressions et publications issues d'un WriteBack sont elles aussi détectées comme des changements et peuvent appeler successivement d'autres Webhook abonnés à ce changement. Les boucles tournant sans fin sont automatiquement vérifiées et bloquées au moment de la création ou de la modification d'un Webhook.

Le créateur (createdBy) de la ressource créée ou modifiée par un WriteBack devient l'utilisateur qui a provoqué ce changement.

Expressions de valeur

La valeur à remplir se récupère avec le même espace réservé ({ /… }) que celui vu précédemment. Toutefois, dans un WriteBack, il y a deux racines pointables.

• Si vous utilisez un seul espace réservé isolément ({ /response/url }), il récupère tel quel la forme d'origine de la valeur (texte, nombre, ensemble).
• Si vous le mélangez à du texte ("Créé : { /payload/sys/id }"), tout est concaténé en un seul texte.
• Lorsque la réponse n'arrive pas en JSON mais en texte brut, récupérez toute la réponse comme texte avec { /response } (vous ne pouvez pas pointer un sous-chemin à l'intérieur).

Manipuler le Content ($content)

C'est l'action qui crée ou modifie un Content à partir de la réponse. Les éléments à définir sont les suivants.

Manipuler le Media ($media)

C'est l'action qui importe comme Media un fichier reçu en réponse ou qui change l'état d'un Media.

$media peut aussi servir de valeur de champ d'un Content. Après avoir importé comme Media un fichier reçu en réponse, vous pouvez relier directement ce Media à un champ et ainsi créer en une fois un « Content contenant une image ».

Le Delete , Archive , Unarchive d'un Media traite non seulement l'information dans la liste, mais aussi le fichier réel présent dans le stockage.

Comment configurer, avec exemples

Dans le WriteBack du studio de contenu, ajoutez les actions une par une avec Ajouter Une Opération. Vous pouvez passer du mode Visual, où vous remplissez les éléments à l'écran, au mode JSON, où vous inscrivez directement un ensemble writeBacks comme ci-dessous. Le résultat est le même dans les deux cas.

Coller une image créée par un LLM externe pour créer un nouveau produit. Importez comme Media l'adresse d'image contenue dans la réponse, et créez un nouveau Content possédant cette image.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Produit Content Type sys.id>" } },
        "fields": {
          "productName": "{ /payload/fields/productName/ko-KR }",
          "photo": { "$media": { "source": "{ /response/data/0/url }", "encoding": "Url" } }
        }
      }
    }
  ]
}

Enrichir le produit où le changement s'est produit. Si vous omettez target, la cible est le Content où le changement s'est produit. Vous remplissez les champs de ce produit avec les valeurs de la réponse.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Update",
        "locale": "en-US",
        "fields": { "productName": "{ /response/translated }" }
      }
    }
  ]
}

Créer uniquement en Draft pour publier après vérification. Si vous désactivez publish, l'élément n'est pas publié et reste en brouillon, ce qui permet de le publier après vérification par une personne.

{
  "writeBacks": [
    {
      "$content": {
        "action": "Create",
        "contentType": { "sys": { "id": "<Content Type sys.id>" } },
        "fields": { "text": "{ /response/choices/0/message/content }" },
        "publish": false
      }
    }
  ]
}

Importer l'image de la réponse comme Media indépendant. Si vous la recevez par adresse, mettez encoding à Url ; si vous la recevez sous forme de données de fichier contenues dans la réponse, mettez Base64.

{
  "writeBacks": [
    { "$media": { "action": "Create", "source": "{ /response/data/0/url }", "encoding": "Url" } }
  ]
}

Delete , Publish , Unpublish , Archive , Unarchive ont la même forme. Si vous n'indiquez que action et la cible target à changer, seul l'état de cette cible change (si la cible est omise, c'est l'élément où le changement s'est produit). Par exemple, pour publier un Content indiqué par la réponse, inscrivez ceci.

{
  "writeBacks": [
    { "$content": { "action": "Publish", "target": "{ /response/contentId }" } }
  ]
}

Si vous ajoutez plusieurs actions, elles s'exécutent dans l'ordre où elles sont inscrites. On les enchaîne ainsi : « remplir le produit avec le résultat de la traduction, puis importer l'image promotionnelle comme Media ».

Vérifier le résultat d'exécution

Vous vérifiez comment s'est déroulée chaque action de WriteBack dans l'historique des appels du Webhook. Pour chaque action, les éléments suivants sont conservés.

Pour une action réussie, l'ID de résultat permet de retrouver quelle ressource a été créée ou modifiée. Si la réponse n'est pas 2xx, le WriteBack n'est pas exécuté du tout et l'historique de résultat reste donc vide.

À savoir

• Un seul changement déclencheur. Si un même Webhook capte à la fois l'enregistrement (Create) et la publication (Publish), le programme externe peut être appelé deux fois. Pour un Webhook qui utilise un WriteBack, ne choisissez qu'un seul changement.
• Il ne fait que transférer des valeurs, il ne calcule pas. Il se limite à prélever des valeurs de la réponse et à les insérer ; il ne fait pas de traitement comme des branchements conditionnels ou des boucles.
• Il ne réessaie pas. Si un problème survient en cours de traitement, cette action peut être perdue telle quelle.
• Empêcher la création non maîtrisée. Pour un Content Type qui n'est créé que par WriteBack, il est préférable de restreindre les permissions afin qu'un utilisateur ordinaire ne puisse pas le créer lui-même directement.

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