Webhooks

Therefore™ prend en charge les webhooks pour assurer une intégration en temps réel pilotée par les événements avec les systèmes tiers.

Le dispositif permet de créer ou de mettre à jour des documents et des dossiers, de déclencher des workflows et de réveiller des composants système tels que Therefore™ Content Connector ou des services Web référencés en fonction des appels de webhooks entrants.

Vous trouverez un exemple de configuration de webhook à la page suivante :

Utilisation de webhooks

Des rubriques avancées relatives aux webhooks (ajout d'une réservation d'URL, instructions relatives au test des signatures HMAC avec Postman, etc.) sont disponibles dans Ressources complémentaires :

Lien externe vers la page Ressources complémentaires relative aux webhooks

Configuration requise

• Pour utiliser des webhooks, vous devez installer le service XML à l'aide du programme d'installation de Therefore™. Le fournisseur tiers qui envoie le webhook doit pouvoir y accéder.

• Les données utiles d'un webhook doivent être au format Json en UTF-8.

• Toute action qui modifie les données sur le système Therefore™ requiert la signature du webhook avec HMAC-SHA256. Cet impératif s'applique spécifiquement aux actions Créer un dossier/un document et Mettre à jour données d'index.

Paramètres de webhook

Boîte de dialogue Webhook

Cette boîte de dialogue vous permet de configurer la signature du webhook et l'action associée.

Vous ne pouvez pas ajouter un corps de réponse. La réponse est systématiquement vide.

Les codes d'état HTTP valides sont 200 OK, 400 Bad Request (Requête incorrecte) ou 401 Unauthorized (Non autorisé). Vous ne pouvez pas configurer les codes d'état HTTP.

Nom
Entrez un nom descriptif de webhook.

Point de terminaison
Point de terminaison dans Therefore™ où arrivent les appels de webhook. Lorsque vous configurez les appels issus d'un service tiers, ce point de terminaison doit être partagé avec les fournisseurs de service tiers, pour qu'ils connaissent la destination des appels de webhook. Vous ne pouvez pas personnaliser l'URL des points de terminaison de webhook.

Copier dans le Presse-papiers Pour copier l'URL de point de terminaison dans votre Presse-papiers, cliquez sur ce bouton situé sur la droite du champ Point de terminaison.

Signature HMAC
Les appels de webhook non signés ne peuvent pas modifier les données. Ils servent uniquement d'appels de réveil pour démarrer Therefore™ Content Connector, des workflows ou un service Web référencé. Pour valider un appel de webhook, une signature HMAC‑SHA256 vérifiée par détection automatique est requise.

Vous trouverez des exemples de signatures HMAC valides à la page suivante :

Signature HMAC

Clé secrète partagée
Entrez une clé secrète fournie par le service tiers d'où sont émis les webhooks qui mènent à ce point de terminaison. L'utilisateur ne voit pas la clé secrète entrée.

En-tête de signature
Entrez dans ce champ le nom d'un en-tête de signature.

En-tête d'horodatage
Vous pouvez entrer dans ce champ un en-tête d'horodatage facultatif.

Lorsqu'un horodatage est utilisé, il est comparé à l'horodatage du serveur en cours. Si l'écart dépasse 5 minutes, le webhook n'est pas traité. L'écart de temps autorisé n'est pas configurable.

Liste verte d'adresses IP
Cliquez sur le bouton Ajouter ou Supprimer à côté de ce champ pour définir au format CIDR des adresses ou des plages IP autorisées à appeler le webhook. Cette liste verte d'adresses IP est imposée par Therefore™.

Seul IPv4 est pris en charge par la liste verte. IPv6 n'est pas autorisé. Si vous configurez une liste verte, le webhook ne peut plus être utilisé depuis une adresse IPv6.

Actions
Configurez les actions que devra exécuter Therefore™ après avoir reçu de nouvelles informations via un appel de webhook. Les conditions sont traitées de haut en bas. Chaque webhook ne peut déclencher qu'une seule action. Les actions configurées sont recensées dans le champ.

Barre d'outils d'icônes relatives aux actions

En cliquant sur un bouton dans la barre d'outils, vous pouvez créer des actions ou modifier et déplacer des actions existantes.

Icône	Description
	Ajoute une nouvelle action.
	Modifie une action existante.
	Supprime une action.
	Décale la demande d'action vers le haut dans la liste. Les appels sont exécutés de haut en bas par défaut.
	Décale la demande REST vers le bas dans la liste.

Lorsque vous cliquez sur le bouton Nouvelle action, un menu déroulant s'ouvre. Sélectionnez dans ce menu l'action appropriée. Les actions disponibles sont indiquées ci-dessous. La sélection d'une action ouvre une boîte de dialogue dans laquelle vous pouvez configurer les paramètres correspondants.

Une seule action est exécutée par webhook. Même si vous configurez plusieurs actions, seule la première action pour laquelle le filtre établit une correspondance et qui n'est pas ignorée est exécutée.

Nouvelle action - Options du menu

Créer un document/dossier

Configurez une action qui crée un document ou un dossier lorsque des informations sont reçues via le webhook. Cette action génère un document vide (en d'autres termes, sans fichier) ou un dossier vide.

L'option ouvre la boîte de dialogue Action Nouveau document/dossier, dans laquelle vous pouvez configurer l'action.

Action Nouveau document/dossier

Si vous sélectionnez cette action, les onglets Filtre, Mise à jour et Démarrer workflow sont disponibles.

Mettre à jour données d'index

Configurez une action qui met à jour les données d'index d'un document existant lorsque des informations sont reçues via le webhook. Cette option ouvre la boîte de dialogue Action Mettre à jour données d'index, dans laquelle vous pouvez configurer l'action.

Action Mettre à jour les données d'index

Si vous sélectionnez cette action, les onglets Filtre, Rechercher, Mise à jour et Démarrer workflow sont disponibles.

Déclencher Content Connector

Configurez une action qui réveille Therefore™ Content Connector lorsque des informations sont reçues via le webhook. Cette option ouvre la boîte de dialogue Action Déclencher Content Connector, dans laquelle vous pouvez configurer l'action.

Action Déclencher Content Connector

Si vous sélectionnez cette action, les onglets Filtre et Content Connector sont disponibles.

Déclencher le service Web référencé

Configurez une action qui réveille Therefore™ Content Connector lorsque des informations sont reçues via le webhook. Cette option ouvre la boîte de dialogue Action Déclencher le service Web référencé, dans laquelle vous pouvez configurer l'action.

Action Déclencher le service Web référencé

Si vous sélectionnez cette action, les onglets Filtre et Service Web référencé sont disponibles.

Boîte de dialogue Actions - Onglets

Filtre

Cet onglet vous permet de configurer un filtre relatif aux valeurs spécifiques des attributs Json, afin de pouvoir exécuter l'action spécifiée lorsque la valeur est identifiée dans les données utiles des données entrantes issues d'un appel de webhook.

Le filtre de webhook s'appuie sur des pointeurs Json. Les types de données Json pris en charge sont les suivants :

• Texte

• Nombres entiers (mais pas les nombres décimaux)

• Opérateurs booléens

• Valeur Null

Aucun autre type de données n'est pris en charge.

Vous trouverez des exemples de configurations de filtre de webhook valides à la page suivante :

Exemples de filtre de webhook

Chemin Json

Entrez le nom de la propriété dans la colonne Chemin Json. Le chemin Json respecte la casse. Entrez le nom de la propriété au format suivant, qui débute par une barre oblique sans guillemets :

/property

Valeur attendue

Entrez la valeur JSON attendue dans cette colonne. « Valeur attendue » ne respecte pas la casse. Utilisez le format suivant, sans guillemets :

expected.value

Ajouter/Supprimer

Utilisez les boutons Ajouter et Supprimer pour modifier le nombre de lignes de la table Filtre.

Tester le filtre

Utilisez ce bouton pour tester le filtre avec les données JSON chargées depuis un fichier ou le Presse-papiers. Vous pouvez ainsi vérifier le filtre avec un exemple de réponse JSON copié dans la documentation du fournisseur de service tiers.

Profil d'indexation

Cet onglet vous permet de créer un profil d'indexation associé à la nouvelle catégorie ou au nouveau dossier généré lorsque des informations sont reçues via le webhook.

Catégorie/définition de dossier cible

Indiquez la catégorie ou la définition de dossier dans laquelle doit être créé le nouveau document ou dossier. Cliquez sur le bouton points de suspension pour ouvrir un menu déroulant, dans lequel vous pouvez sélectionner une catégorie ou une définition de dossier dans le référentiel.

Script

Vous pouvez créer un script qui sera exécuté avant l'exécution de l'affectation des champs.

Mode d'ajout automatique

Vous pouvez définir le mode d'ajout automatique associé aux documents mémorisés avec ce profil. Consultez la page de référence ci-dessous pour obtenir des informations complémentaires sur l'ajout automatique.

Ajout automatique

Affectation

Lorsque vous avez choisi une catégorie, cliquez sur la flèche déroulante du champ d'index à définir. Si la valeur du champ d'index doit provenir du document d'origine à signer envoyé, renseignez Catégorie de document existante et sélectionnez le champ d'index dans la liste.

Charger Json...

Lorsque vous cliquez sur ce bouton, un menu déroulant s'ouvre. Il contient les options « à partir d'un fichier » et « à partir du Presse-papiers », qui vous permettent de charger une réponse Json. Vous pourrez utiliser celle-ci pour configurer les affectations.

Rechercher

Cet onglet vous permet de définir les critères de recherche de documents Therefore™ à mettre à jour à partir des informations reçues via le webhook.

Vous ne pouvez pas utiliser d'opérateurs de recherche tels que « < », « > » ou autres. La recherche utilise uniquement la comparaison d'égalité (« = »).

Les paramètres de l'onglet Rechercher sont similaires aux paramètres de l'onglet Profil d'indexation.

Catégorie

Utilisez le bouton points de suspension pour sélectionner une catégorie dans laquelle rechercher le document à mettre à jour.

Script

Ajoutez un script de recherche à exécuter avant le traitement des affectations.

Ajouter affectation

Cliquez avec le bouton droit de la souris sur un espace vide de la table Affectations pour afficher cette option. Lorsque vous cliquez dessus, la boîte de dialogue Sélection des champs ou des catégories s'ouvre. Elle vous permet de sélectionner des objets Therefore™ compris entre le niveau dossier et le niveau champ pour lesquels vous voulez ajouter des affectations. Cochez la case vide à côté d'un objet Therefore™ pour le sélectionner. La sélection d'une catégorie remplit la table en insérant une ligne par champ de données d'index de la catégorie.

Champ de catégorie

Cette colonne recense les champs de données d'index de la catégorie sélectionnée.

Chaîne de recherche

Cette colonne vous permet de définir les chaînes de recherche associées aux champs de catégorie requis. Utilisez des affectations ou des variables pour trouver le document contenant la valeur de champ de données d'index à rechercher.

Charger Json

Lorsque vous cliquez sur ce bouton, un menu déroulant s'ouvre. Il contient les options « à partir d'un fichier » et « à partir du Presse-papiers », qui vous permettent de charger une réponse Json utilisée pour configurer les affectations de recherche.

Mise à jour

Cet onglet vous permet de configurer des affectations pour mettre à jour les champs de données d'index lorsque des informations sont reçues via le webhook.

Les paramètres de l'onglet Mise à jour sont similaires aux paramètres de l'onglet Profil d'indexation.

Script

Ajoutez un script à exécuter avant le traitement des affectations.

Champ de catégorie

Cette colonne recense les champs de données d'index de la catégorie sélectionnée.

Affectation

Cette colonne vous permet de définir les affectations associées aux champs de catégorie requis. Utilisez des affectations ou des variables pour mettre à jour le document à l'aide des nouvelles valeurs de champs de données d'index reçues via le webhook.

Charger Json

Lorsque vous cliquez sur ce bouton, un menu déroulant s'ouvre. Il contient les options « à partir d'un fichier » et « à partir du Presse-papiers », qui vous permettent de charger une réponse Json. Vous pourrez utiliser celle-ci pour configurer les affectations destinées à mettre à jour les champs.

Démarrer workflow

Cet onglet vous permet de définir le workflow à démarrer en même temps que l'action configurée. Le webhook fait office d'appel de réveil du workflow.

Aucun

Aucun processus de workflow ne démarre en même temps que l'action.

Processus par défaut

Le processus de workflow par défaut de la catégorie démarre en même temps que l'action.

Processus personnalisé

Ouvre un menu déroulant dans lequel vous pouvez sélectionner l'un des workflows à démarrer pour cette catégorie.

Déclencher Content Connector

Cet onglet vous permet d'associer l'action à une source de Content Connector à interroger lorsque des informations sont reçues via le webhook.

Seules les sources de Content Connector actives sont interrogées.

Un intervalle de temps non configurable pouvant atteindre 1 minute sépare la réception de webhook et la recherche par la source de nouveaux éléments en attente. Les retards peuvent s'accumuler si Content Connector traite déjà des sources ou est occupé.

Source de Content Connector

Sélectionnez dans le menu déroulant une source de Content Connector à associer à cette action.

Déclencher le service Web référencé

Cet onglet vous permet d'associer l'action à un service Web référencé à synchroniser lorsque des informations sont reçues via le webhook.

Cette action est immédiate. Si une synchronisation est en cours d'exécution, un délai de 10 secondes au plus sépare la fin de la synchronisation en cours et le déclenchement d'une nouvelle synchronisation pour le service Web référencé indiqué.

Service Web référencé

Sélectionnez dans le menu déroulant un service Web référencé à associer à cette action.

Cases à cocher

Inclure les données utiles dans le journal

Consigne le corps des appels de webhook à des fins de dépannage. La taille maximale des données utiles ne doit pas dépasser 10 Mo. Si elle dépasse 10 Mo, les données utiles ne sont pas consignées, même si le paramètre Inclure les données utiles dans le journal est activé.

Le webhook est actif

Désactive ou active le traitement.

La déduplication n'est actuellement pas prise en charge. Par conséquent, si le même webhook est à nouveau envoyé, il est à nouveau traité.