Webhooks

1. Vue d'ensemble

Les webhooks permettent de notifier un système externe lorsqu’un utilisateur effectue des actions spécifiques dans Constellio.

Les notifications sont envoyées sous la forme de requête REST de type POST avec un body JSON qui contient les informations sur l’action qui a été effectuée ainsi qu’une liste de métadonnées des enregistrements en question. La liste des métadonnées à inclure dans la requête peut être configurée par l’utilisateur (Voir « Configurer un webhook »).

2. Pilotage

Une page de pilotage « Gérer les webhooks » permet de visualiser la liste des webhooks définis pour le système et d’effectuer différentes actions sur ceux-ci. Un utilisateur doit posséder la permission « Gérer les webhooks » pour accéder à cette page.

La page Liste des webhooks présente la liste des webhooks actifs et inactifs dans deux onglets. Un bouton « Ajouter » permet de configurer un nouveau webhook et de l’ajouter à cette liste.

Pour désactiver ou activer un webhook, il suffit de cliquer l’icône « Désactiver » ou « Activer » dans l’onglet correspondant.

Les actions suivantes sont disponibles pour chacun des éléments de la liste de webhooks :

• Consulter : Permets de consulter les métadonnées de base d’un webhook
• Modifier : Permets de modifier les informations d’un webhook existant
• Désactivé/activé : Permets d’activer ou de désactiver un webhook (dépendamment du statut actuel du webhook). Aucune notification ne sera envoyée pour les webhooks dont le statut est « Inactif ».
• Supprimer : Permets de supprimer un webhook. Cette action est irréversible.

3. Configurer un webhook

La configuration d’un nouveau webhook peut être effectuée à partir de la page de pilotage « Gérer les webhooks » en cliquant sur le bouton « Ajouter » ou sélectionnant l’icône « Modifier » pour modifier un webhook existant.

À la création d’un nouveau webhook, celui-ci aura automatiquement le statut « Actif ».

4. Filtres

En plus du type d’évènement et du type de schéma, il est possible de définir des conditions de déclenchement d’un webhook plus spécifiques en y ajoutant des filtres. Une requête sera envoyée lors de l’action sur un enregistrement uniquement si les valeurs des métadonnées de l’enregistrement correspondent à celles définies dans le filtre (après la modification).

Les conditions de déclenchement spécifiques sur les métadonnées fonctionnent de la même façon que les critères de recherche lors d’une recherche avancée. Il n’y a pas de limite sur le nombre de critères qui peuvent être ajoutés pour un webhook.

Exemples:

Webhook pour envoyer une notification lors de la modification de tâche dont le statut est « En cours », uniquement si elle a été créée par un utilisateur spécifique

5. Configurations système

Des configurations système doivent être définies pour utiliser les webhooks. Ces configurations s’appliquent à l’ensemble des webhooks dans toutes les collections de l’environnement.

6. Fonctionnement

6.1 Appel de Webhook

Une fois le webhook défini, un processus en arrière-plan analysera toutes les actions effectuées par les utilisateurs du système. Lorsqu’un utilisateur effectue une action qui correspond aux critères définis dans un des Webhooks (par exemple, « Modifier un document dont le titre contient le mot « formulaire »), Constellio ajoutera le webhook à une liste « Requêtes de webhooks à envoyer »

Toutes les requêtes contenues dans cette liste seront envoyées à un intervalle régulier. Cet intervalle peut être défini dans la configuration système « Délai d’envoi des webhooks ».

Lorsque plusieurs actions ont été effectuées pour le même webhook (par exemple, si plusieurs documents qui contiennent le mot « formulaire » ont été modifiés au courant de l’intervalle), les informations de tous les enregistrements concernés seront envoyées dans la même requête.

6.2 Contenu des requêtes

Les requêtes envoyées contiennent les informations de base du webhook, ainsi que les métadonnées à envoyer définies lors de la configuration du webhook pour tous les enregistrements concernés par l’action.

6.3 Exemple de contenu d’une requête envoyée par un webhook

{
   "webhookId":"00000000417",
   "webhookCode":"modifyDocsWebhook_code",
   "data":{
      "records":[
         {
            "id":" 00000000512",
            "collection":"zeCollection",
            "document_default_title":"Abeille - Document analogique”
            "document_default_modifiedOn":"2022-05-30T14:18:06.138"
         }
      ]
   },
   "secretToken":"mySecretToken",
   "webhookName":"Modification de document (titre : « Formulaire ») ",
   "eventType":"MODIFICATION",
   "user":"admin"

7. Mécanique de reprise

Dans le cas où la requête envoyée par le webhook n’a pas été reçue ou acceptée par le serveur distant, une mécanique permet de retenter l’envoi de la requête.

Initialement, une requête qui a échoué est conservée dans la liste de requêtes à envoyer et une nouvelle tentative sera effectuée au prochain intervalle.

Après un certain nombre de tentatives ratées¹, la requête est transférée vers une liste « requêtes de webhooks à relancer ». Le fonctionnement de cette liste est semblable à la liste d’envoi, mais il est possible d’y définir un intervalle différent². Typiquement, l’intervalle défini pour la liste de relance devrait être plus long que celui de la liste d’envoi.

Afin d’éviter que des requêtes tournent en boucle dans la liste de relance, il est également possible de définir un nombre maximal de tentatives pour les relances³ (On peut également y saisir la valeur -1 pour ne pas définir de nombre maximal). Une fois que le nombre maximal est atteint, la requête est retirée de la liste.

8. Diagramme du fonctionnement de la mécanique d'envoi et de reprise

9. Configurations

Vous retrouverez dans cette section toutes les configurations du système impactant les webhooks. Pour en savoir plus sur les configurations, consulter l'article «Configurations du système».