Configurer les webhooks

Un webhook permet de notifier un serveur externe d'un événement qui se produit dans Akuiteo. L'objectif est d'exploiter informatiquement les événements détectés.

Exemple

Si un système externe à Akuiteo est utilisé pour la gestion des ressources humaines, un webhook peut être configuré afin de notifier ce système externe de la création ou de la suppression de collaborateurs.

Dans le cadre des webhooks, un événement est composé de deux informations majeures :

L'objet concerné (ex : un collaborateur, une dépense, etc.) ;
L'action effectuée sur cet objet (ex : création, modification, suppression).

Lorsqu'un webhook est configuré pour détecter un certain événement et que celui-ci se produit, le webhook envoie une requête vers une adresse web appelée point de terminaison.

Un point de terminaison (ou endpoint) est un lien hypertexte sur un serveur externe qui permet de recevoir les requêtes envoyées par des webhooks.

Chaque requête contient des données concernant l'événement qui s'est produit, ou à minima l'identifiant de l'objet associé à l'événement.

Le webhook détecte les événements dans la globalité d'Akuiteo. Par exemple, il n'est pas possible de configurer un webhook afin qu'il détecte un événement effectué par certains utilisateurs en particulier.

Les webhooks sont configurés dans la Console d'administration, depuis Configuration > Webhooks.

Créer un webhook

Dans l'écran Webhooks, cliquez sur Créer un nouveau webhook.

Renseignez les informations de la section Propriétés :

Champ	Description
Nom	Renseignez un libellé pour nommer le webhook.
EndPoint (URL)	Renseignez le lien correspondant au point de terminaison du webhook. Le point de terminaison est le lien hypertexte sur un serveur externe qui reçoit les requêtes envoyées par le webhook. Cliquez sur le bouton Test à droite du champ pour vérifier l'accessibilité et la validité du point de terminaison renseigné.
Activé	Il est possible d'activer ou de désactiver le webhook en cliquant sur l'option. Le webhook doit être activé pour fonctionner. S'il est désactivé, il ne fonctionnera pas et ne pourra envoyer aucune requête. Un webhook peut être activé à tout moment à partir de l'écran Webhooks.

Champ

Description

Nom

Renseignez un libellé pour nommer le webhook.

EndPoint (URL)

Renseignez le lien correspondant au point de terminaison du webhook.

Le point de terminaison est le lien hypertexte sur un serveur externe qui reçoit les requêtes envoyées par le webhook.

Cliquez sur le bouton Test à droite du champ pour vérifier l'accessibilité et la validité du point de terminaison renseigné.

Activé

Il est possible d'activer ou de désactiver le webhook en cliquant sur l'option.

Le webhook doit être activé pour fonctionner. S'il est désactivé, il ne fonctionnera pas et ne pourra envoyer aucune requête.

Un webhook peut être activé à tout moment à partir de l'écran Webhooks.

Renseignez les informations de la section Notification :

Important

Cette fonctionnalité est soumise au feature flag Domaine Transverse > Libellé Notification Echec Webhook.

Champ	Description
Email	Renseignez l'adresse mail à laquelle envoyer une notification lorsqu'une erreur survient sur le webhook.
Activer la notification en cas d'échec	Cliquez sur l'option pour activer ou désactiver l'envoi de mail lors de la détection d'un échec sur le webhook.

Renseignez les informations de la section Sécurité :

Champ	Description
Secret	Renseignez le secret si le point de terminaison utilise un secret. Important Le point de terminaison doit être un site en HTTPS pour que le secret fonctionne. Note La signature est générée grâce au protocole cryptographique HMAC-SHA256 en Base64. Fonctionnement Lorsqu'une requête est envoyée par le webhook en utilisant un secret, elle comporte une signature insérée en tant qu'entête. Cette signature est une combinaison unique dépendant mathématiquement du contenu de la requête et du secret utilisé. Il est possible que le système externe recevant la requête soit programmé pour vérifier cette signature. Dans ce cas, ce système essaiera de régénérer la signature grâce au contenu de la requête et au secret : Si la signature régénérée est identique à celle dans l'entête de la requête, le secret est correct et le contenu de la requête n'a pas été altéré. L'authenticité de la requête est alors assurée. Si la signature régénérée est différente de celle présente dans l'entête de la requête, il est possible que le secret soit incorrect ou que le contenu de la requête ait été altéré. L'authenticité de la requête n'est alors pas assurée.
Header name	Renseignez le nom de l'entête si le point de terminaison utilise un entête de sécurité. L'entête est un élément de sécurité qui peut être utilisé par le point de terminaison afin qu'il accepte uniquement les requêtes de webhooks comportant cet entête ainsi que sa valeur renseignée dans le champ Header value.
Header value	Renseignez la valeur liée à l'entête renseignée dans le champ Header name si le point de terminaison utilise un entête de sécurité. Si la valeur de l'entête renseignée dans le champ Header value est différente de celle attendue au point de terminaison, la requête pourrait être considérée non authentique et ne pas provenir d'Akuiteo.

Champ

Description

Secret

Renseignez le secret si le point de terminaison utilise un secret.

Important

Le point de terminaison doit être un site en HTTPS pour que le secret fonctionne.

Note

La signature est générée grâce au protocole cryptographique HMAC-SHA256 en Base64.

Fonctionnement

Lorsqu'une requête est envoyée par le webhook en utilisant un secret, elle comporte une signature insérée en tant qu'entête. Cette signature est une combinaison unique dépendant mathématiquement du contenu de la requête et du secret utilisé. Il est possible que le système externe recevant la requête soit programmé pour vérifier cette signature. Dans ce cas, ce système essaiera de régénérer la signature grâce au contenu de la requête et au secret :

Si la signature régénérée est identique à celle dans l'entête de la requête, le secret est correct et le contenu de la requête n'a pas été altéré. L'authenticité de la requête est alors assurée.
Si la signature régénérée est différente de celle présente dans l'entête de la requête, il est possible que le secret soit incorrect ou que le contenu de la requête ait été altéré. L'authenticité de la requête n'est alors pas assurée.

Header name

Renseignez le nom de l'entête si le point de terminaison utilise un entête de sécurité.

L'entête est un élément de sécurité qui peut être utilisé par le point de terminaison afin qu'il accepte uniquement les requêtes de webhooks comportant cet entête ainsi que sa valeur renseignée dans le champ Header value.

Header value

Renseignez la valeur liée à l'entête renseignée dans le champ Header name si le point de terminaison utilise un entête de sécurité.

Si la valeur de l'entête renseignée dans le champ Header value est différente de celle attendue au point de terminaison, la requête pourrait être considérée non authentique et ne pas provenir d'Akuiteo.

Renseignez les informations de la section Événement :

Champ	Description
Event type	Sélectionnez le type de l'événement depuis la liste déroulante. Le type de l'événement correspond au type d'objet sur lequel le webhook doit détecter une certaine action (ex : un collaborateur, une dépense, etc.).
Event action(s)	Sélectionnez l'action de l'événement depuis la liste déroulante. Il s'agit de l'action pour laquelle le webhook doit envoyer une requête à chaque fois qu'elle se produit sur le type d'objet en question (ex : création, modification, suppression).

Champ

Description

Event type

Sélectionnez le type de l'événement depuis la liste déroulante.

Le type de l'événement correspond au type d'objet sur lequel le webhook doit détecter une certaine action (ex : un collaborateur, une dépense, etc.).

Event action(s)

Sélectionnez l'action de l'événement depuis la liste déroulante.

Il s'agit de l'action pour laquelle le webhook doit envoyer une requête à chaque fois qu'elle se produit sur le type d'objet en question (ex : création, modification, suppression).

Cliquez sur Créer.

Le webhook est créé. Il doit être activé pour fonctionner.

Modifier un webhook

Sur la ligne du webhook à modifier, cliquez sur

Effectuez les modifications souhaitées.

Cliquez sur Mettre à jour.

Le webhook est modifié.

Configurer les propriétés de connexion

Sous la section Propriétés de connexion à Akuiteo, renseignez les identifiants de l'utilisateur utilisé pour se connecter à Akuiteo dans le cadre des webhooks :

Champ	Description
Utilisateur Akuiteo	Renseignez l'identifiant de l'utilisateur utilisé pour le traitement des webhooks et cliquez sur Enregistrer. Il est conseillé de renseigner un utilisateur technique, c'est-à-dire un utilisateur coché Utilisateur technique ? sur l'Application Desktop puis dans Tiers > Gestion des utilisateurs.
Mot de passe Akuiteo	Renseignez le mot de passe de l'utilisateur utilisé pour le traitement des webhooks et cliquez sur Enregistrer.
Timeout (endPoint)	Renseignez la valeur (en ms) à partir de laquelle le webhook arrête d'attendre la réponse du serveur (Timeout) et cliquez sur Enregistrer.
Nombre maximum d'essais (1-8)	Renseignez le nombre maximum d'essais en cas d'échec de la requête. Une requête est considérée échouée lorsque le code HTTP de la réponse obtenue commence par un chiffre différent de 2.
Mode de réessai de production	Cette option permet de définir le comportement des essais lors de l'échec des requêtes. L'option est cochée par défaut. Lorsque l'option est cochée, l'intervalle entre chaque essai augmente exponentiellement entre chaque essai. La formule de calcul du délai est : Timeout (endPoint) + numéro d'essai⁴ Cette disposition est recommandée si vous utilisez les webhooks en conditions réelles car elle permet de mieux gérer l'utilisation simultanée de nombreux webhooks. Lorsque l'option est décochée, l'intervalle entre chaque essai est de 3 secondes. Cette disposition est recommandée uniquement si vous souhaitez tester le bon fonctionnement des webhooks dans un environnement de test car elle réduit l'intervalle des essais.

Cliquez sur le bouton Tester pour tester la connexion à l'interface Webhook à partir des valeurs renseignées.

Consulter les requêtes des webhooks

Les colonnes suivantes présentent des informations sur les réponses aux requêtes des webhooks :

Champ	Description
Dernière réponse	Affiche le code de réponse HTTP de la dernière requête effectuée par le webhook. Si le code obtenu commence par le chiffre 2, la requête a réussi et la cellule est verte. Si le code obtenu commence par le chiffre 4, la requête a échoué et la cellule est rouge. Si le code obtenu est N/A, la requête n'a pas encore été envoyée.
Appels réussis	Affiche le nombre de requêtes qui sont parvenues avec succès au point de terminaison.
Nb total d'appels	Affiche le nombre de fois que le webhook a détecté un événement et a donc envoyé une requête vers le point de terminaison.
Log	L'icône dans cette colonne permet de télécharger le fichier de log du webhook. Le log est un fichier texte d'extension .log qui contient l'historique de toutes les requêtes effectuées par le webhook. Il est possible de l'ouvrir grâce à un éditeur de texte.