Webhook

Un Webhook est une configuration qui envoie une requête HTTP vers une URL externe prédéfinie lorsqu'un événement se produit dans un Space (par exemple, la création ou la publication d'un Content). Il sert à intégrer des systèmes externes ou à automatiser des tâches. Par exemple, vous pouvez le configurer pour appeler un serveur de notification interne ou une API externe chaque fois qu'un Content de produit est publié.

Un Webhook ne se limite pas à envoyer une requête : il peut aussi configurer un WriteBack qui reçoit la réponse et la réécrit dans un Content ou un Media. C'est ainsi que vous construisez un flux de travail asynchrone qui absorbe le résultat d'une API externe sous forme de données à l'intérieur du Space. Le Webhook est une ressource enfant du Space dans CMA, et son chemin repose sur /spaces/{spaceId}/webhooks.

Structure de la ressource

Voici la réponse d'une consultation unitaire du Webhook « Notification de modification de produit ». Outre sys (propriétés système), il comporte des champs de configuration comme la cible d'envoi, les événements souscrits et les conditions de déclenchement.

{
  "sys": {
    "id": "3trmXRM3RqbgSnifyg7PWhk01Examp",
    "type": "Webhook",
    "space": { "sys": { "id": "HnQ32YiH", "type": "Refer", "targetType": "Space" } },
    "createdBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "createdAt": "2026-06-18T11:30:00.000Z",
    "updatedBy": { "sys": { "id": "3p4tcFbQRwz503VXdtHXNI5dZH5TVB", "type": "Refer", "targetType": "User" } },
    "updatedAt": "2026-06-18T11:30:00.000Z",
    "version": 1
  },
  "name": "Notification de modification de produit",
  "filters": [
    { "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }
  ],
  "headers": [
    { "key": "X-Source", "value": "weegloo", "secret": false }
  ],
  "httpBasicUsername": "dailywear",
  "topics": ["Content.Create", "Content.Publish"],
  "transformation": { "method": "POST", "contentType": "application/json", "includeBody": true },
  "url": "https://api.dailywear.example/webhooks/products",
  "activate": true
}

Clés principales :

• sys.id : identifiant unique du Webhook. Il s'insère dans le {webhookId} des chemins de consultation unitaire, de modification et de suppression.
• url : URL externe cible à appeler lorsqu'un événement se produit.
• topics : tableau qui détermine les événements à souscrire. La section topics ci-dessous en décrit le format.
• filters : conditions qui déclenchent réellement parmi les événements souscrits. Décrites dans filters ci-dessous.
• transformation : configuration qui modifie la forme (méthode, corps, etc.) de la requête sortante. Décrite dans transformation ci-dessous.
• writeBacks : tableau d'opérations qui reçoivent la réponse externe et la réécrivent dans un Content ou un Media. Il est absent de l'exemple ci-dessus. Décrit dans writeBacks ci-dessous.

Propriétés système (sys)

Chaque Webhook place ses propriétés système communes dans l'objet sys. Les champs space, createdBy et updatedBy se présentent sous la forme Refer ({ "sys": { "id", "type": "Refer", "targetType" } }).

Le Webhook étant une ressource de configuration, il n'a pas de notion de publication. Contrairement à un Content ou à un Content Type, il ne possède pas de propriétés d'état de publication telles que publish, archive ou status ; il n'a que version pour le suivi des modifications. Son activation et sa désactivation ne se contrôlent pas par la publication, mais par le champ de corps activate.

Propriétés du corps

Le corps du Webhook (les valeurs de configuration envoyées lors de la création ou de la modification et renvoyées dans la réponse) se compose des champs suivants.

Chaque élément de headers se compose de key (requis), value (requis) et secret (facultatif, boolean). La valeur d'un en-tête dont secret vaut true est masquée dans la réponse. Placez les valeurs qui ne doivent pas être exposées, comme une clé d'API, dans un en-tête secret: true.

topics

Chaque élément de topics suit le format {ressource}.{action}. Par exemple : Content.Create, Content.Publish, Media.Create.

L'action est l'une des suivantes, ou bien *, qui désigne toutes les actions de la ressource (par exemple Content.*).

filters

filters est un tableau qui restreint, parmi les topics souscrits, les conditions qui déclencheront réellement le Webhook. Chaque filtre a la forme suivante.

{ "doc": "sys.contentType.sys.id", "op": "EQ", "value": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" }

• doc : chemin du champ à comparer. L'une des valeurs sys.id, sys.contentType.sys.id, sys.createdBy.sys.id ou sys.updatedBy.sys.id.
• op : opérateur de comparaison. L'une des valeurs EQ, NE, IN, NOT_IN, REGEX ou NOT_REGEX.
• value : valeur de comparaison. Une chaîne pour EQ, NE, REGEX et NOT_REGEX ; un tableau de chaînes pour IN et NOT_IN.

Si vous définissez plusieurs filtres, ils doivent tous être satisfaits pour déclencher (AND). Si filters est vide, tous les événements des topics souscrits déclenchent.

transformation

transformation modifie la forme de la requête HTTP sortante. Si elle n'est pas spécifiée, l'intégralité de la charge utile de la ressource part telle quelle avec la méthode POST par défaut.

writeBacks

writeBacks est un tableau ordonné d'opérations qui, à partir de la réponse externe reçue par le Webhook, réécrivent dans un Content ou un Media. Elles ne s'exécutent dans l'ordre que si l'API externe a répondu avec un code 2xx. Chaque élément contient soit $content (WriteBackContent), soit $media (WriteBackMedia).

Clés de WriteBackContent ($content) :

Clés de WriteBackMedia ($media) :

Voici un exemple de writeBacks qui extrait des valeurs du JSON de la réponse externe pour créer un Content.

"writeBacks": [
  {
    "$content": {
      "action": "Create",
      "contentType": { "sys": { "id": "3trmXRLdJF4GBlAjtcuoZ7Pnxj8dlA" } },
      "locale": "ko-KR",
      "fields": {
        "productName": "{ /response/title }",
        "price": "{ /response/price }"
      },
      "publish": true,
      "unpublish": true
    }
  }
]

{ /response/... } est un modèle JSON Pointer qui extrait une valeur du JSON de la réponse reçue par le Webhook. Les clés de fields (productName, price) sont l'apiName des champs du Content cible. L'exemple ci-dessus place le title de la réponse dans le productName du Content et le price dans price, crée le Content, puis le publie.

API

L'URL de référence de tous les endpoints ci-dessous est https://cma.weegloo.com/v1, et un jeton Bearer authentifiant auprès de CMA est requis dans l'en-tête Authorization. La modification (PUT) et la modification partielle (PATCH) doivent inclure l'en-tête X-Weegloo-Version (le sys.version actuel de la ressource) pour le contrôle de concurrence optimiste.

Documents liés

• Content : les données de corps que le Webhook déclenche ou écrit via WriteBack.
• Media : la ressource fichier que le WriteBack peut créer.
• SpaceRole : pour restreindre à :self l'accès au Content manipulé par le Webhook.