Webhook

Le Webhook est le moyen par lequel IDCloud informe automatiquement votre système lorsqu'un événement se produit dans un parcours de vérification d'identité. Au lieu que votre système demande « est-ce terminé ? », IDCloud appelle votre API dès que l'événement se produit.

Sur cet écran, vous définissez l'adresse de votre API, la façon dont IDCloud s'authentifie auprès d'elle, et ce qui se passe quand elle ne répond pas.

info

À qui cela s'adresse : aux clients qui souhaitent recevoir automatiquement les résultats des parcours, sans interrogation périodique. S'applique aux intégrations byUnico comme byClient.

Ce qui change dans votre système : il reçoit désormais une notification à chaque changement d'état, au lieu d'avoir à interroger IDCloud.

Où le trouver : Portail IDCloud → menu latéral Paramètres → onglet Webhook.

Avant l'existence de cet écran, toute modification de webhook nécessitait un ticket de support — environ 30 tickets par mois pour cela seul. Désormais, vous le faites vous-même, en quelques minutes, aussi bien en Staging qu'en Production.

Avant de commencer

Autorisation d'accès

Votre utilisateur a besoin du profil Configurateur — le même qui donne accès à la Personnalisation du parcours. Si l'onglet Webhook n'apparaît pas, contactez l'administrateur de votre compte.

Comment la configuration est appliquée

Portée	Un webhook par tenant et branche. Il n'y a pas de liste : si un webhook est déjà configuré, il est modifié, pas dupliqué.
Environnements séparés	Le Portail Staging configure le webhook UAT ; celui de Production configure la Production. Configurer l'un n'affecte pas l'autre.
Moment de prise d'effet	Dès l'enregistrement.
Sécurité du secret	Le secret est chiffré et n'est plus jamais affiché en texte clair. Sur l'écran, il est toujours masqué.

Ce qu'il faut avoir sous la main

• L'URL HTTPS de votre API qui recevra les notifications. Elle doit être active et accepter les requêtes avant l'enregistrement.
• Les identifiants attendus par votre API, selon la méthode d'authentification choisie (voir l'étape 3).
• Si votre API a une limite de capacité, le nombre de requêtes par seconde qu'elle supporte.

Ce qu'il faut décider au préalable

Deux décisions techniques dépendent de la personne qui maintient votre API, pas de celle qui exploite le Portail. Il vaut la peine de s'aligner avant d'ouvrir l'écran :

• Quelle méthode d'authentification votre API exige.
• Si vous ajusterez les tentatives de réessai ou les laisserez à la valeur par défaut. La valeur par défaut convient à la plupart des cas.

Étape par étape

Étape 1 — Ouvrez l'onglet Webhook

Dans le Portail IDCloud, cliquez sur l'icône d'engrenage (Paramètres) dans le menu latéral et sélectionnez l'onglet Webhook.

Si vous n'avez pas encore de webhook configuré, l'écran affiche « Aucun webhook créé » et un bouton Créer un webhook. Si vous en avez déjà un, l'écran affiche la carte Votre webhook avec le point de terminaison, le type d'authentification et le secret masqué, ainsi qu'un bouton Configurer le webhook pour le modifier.

Carte « Votre webhook » avec le point de terminaison, le type d'authentification et le secret masqué.

Étape 2 — Saisissez l'URL de votre API

Cliquez sur Créer un webhook (ou Configurer le webhook, si un webhook existe déjà) et remplissez le champ URL client (Point de terminaison), sous « Informations client ».

C'est l'adresse à laquelle IDCloud envoie les notifications. Elle doit être en HTTPS.

Pointez vers une adresse déjà active. IDCloud commence à appeler cette URL dès l'enregistrement. Si elle n'existe pas encore, les premières notifications échoueront et épuiseront les tentatives de réessai avant que votre équipe ne s'en rende compte.

Champ du point de terminaison, avec le texte d'aide sur l'exigence HTTPS.

Étape 3 — Choisissez comment IDCloud s'authentifie auprès de votre API

Sous « Authentification », sélectionnez le Type d'authentification. Il existe quatre options, chacune demandant des champs différents :

Type	Champs affichés	Quand l'utiliser
Aucune	aucun	Votre API n'exige pas d'authentification. À utiliser uniquement si elle dispose d'une autre protection — sans authentification, quiconque découvre l'URL peut lui envoyer des données
API Key	Secret	Votre API valide une clé fixe
Basic Auth	Secret	Votre API utilise un nom d'utilisateur et un mot de passe, façon HTTP Basic
OAuth 2.0	URL d'authentification, Client ID, Secret	Votre API exige un jeton. IDCloud récupère le jeton depuis cette URL et le renouvelle lui-même

Pour OAuth 2.0, l'URL d'authentification est l'adresse où IDCloud récupère le jeton — ce n'est pas l'URL qui reçoit les notifications. Ce sont des adresses différentes, et les inverser est l'erreur la plus courante sur cet écran.

Le Secret est stocké chiffré. Lors de la modification d'un webhook existant, le champ apparaît vide : le remplir écrase le secret actuel, et le laisser vide conserve celui déjà enregistré.

Confirmez la méthode avec la personne qui maintient votre API avant d'enregistrer. Une authentification incorrecte ne produit pas d'erreur à l'écran — elle produit une notification qui échoue silencieusement par la suite, et vous ne le découvrez que lorsqu'un résultat n'arrive pas.

Champ du type d'authentification et les champs d'identifiants correspondants.

Étape 4 — Ajustez les tentatives de réessai, si nécessaire

La section Configuration des tentatives de réessai est facultative et désactivée par défaut. Activez-la uniquement si vous devez modifier le comportement par défaut.

L'activer révèle six champs :

Champ	Ce qu'il contrôle	Valeur par défaut
Tentatives maximales	Combien de fois IDCloud réessaie avant d'abandonner	—
Limite de débit (req/s)	Nombre maximal de notifications par seconde. Réduisez-la si votre API a une capacité limitée	—
Temps minimal (s)	Intervalle minimal entre les tentatives	2 s
Temps maximal (s)	Intervalle maximal entre les tentatives	10 s
Durée maximale (s)	Temps d'attente par tentative avant de la considérer comme un échec	2 s
Doublements maximaux	Facteur de croissance de l'intervalle entre les tentatives (backoff)	5

Le comportement combiné est le suivant : IDCloud essaie, attend le temps minimal, réessaie, et continue d'augmenter l'intervalle selon les doublements maximaux jusqu'au temps maximal — en répétant jusqu'aux tentatives maximales. Chaque tentative individuelle est abandonnée après la durée maximale.

Ajustez la limite de débit avant de toucher au reste. Si votre API s'effondre sous la charge, le problème est un problème de débit, pas de tentatives de réessai — et augmenter les tentatives dans ce scénario aggrave la situation, car cela multiplie les appels. Réduisez d'abord le débit.

Augmenter les tentatives maximales ne remplace pas une API stable. Les tentatives de réessai couvrent une indisponibilité momentanée. Si votre API échoue fréquemment, ce paramètre ne fait que retarder le moment où vous perdez la notification.

Les six champs de tentatives de réessai, affichés après activation du bouton bascule.

Étape 5 — Enregistrer

Cliquez sur Enregistrer. Annuler rejette toutes les modifications et conserve la configuration précédente.

IDCloud valide l'URL du jeton avant de permettre l'enregistrement, lorsque la méthode est OAuth 2.0.

Après l'enregistrement, la carte Votre webhook affiche le point de terminaison et le type d'authentification. Le secret apparaît masqué et ne peut plus être récupéré depuis l'écran — si vous perdez la valeur, vous devrez en définir une nouvelle.

Effectuez un vrai test avant de considérer que c'est terminé. Démarrez un parcours en Staging et confirmez que la notification est arrivée à votre API. L'écran confirme que la configuration a été enregistrée, pas que votre API l'a reçue.

FAQ

Puis-je enregistrer plus d'un webhook ? Non. C'est un webhook par tenant et branche. S'il en existe déjà un, il est modifié — il n'y a aucun moyen d'en créer un second.

Je l'ai configuré en Staging. S'applique-t-il aussi à la Production ? Non. Les environnements sont indépendants : le Portail Staging configure le webhook UAT, et celui de Production configure la Production. Vous devez répéter la configuration dans le Portail Production.

Comment voir le secret que j'ai enregistré ? Ce n'est pas possible. Il est chiffré à l'enregistrement et toujours affiché masqué. Si vous avez perdu la valeur, enregistrez-en une nouvelle via le champ Secret — le remplir écrase la précédente.

J'ai modifié le webhook mais je ne veux pas changer le secret. Que dois-je faire ? Laissez le champ Secret vide. La valeur actuelle est conservée.

Comment supprimer un webhook ? L'écran ne propose pas de suppression. Pour retirer la configuration, contactez le support Unico. Si l'objectif est simplement d'arrêter de recevoir des notifications ou de changer la destination, modifiez plutôt l'URL.

J'ai enregistré et les notifications n'arrivent pas. Vérifiez, dans cet ordre : l'URL est correcte et en HTTPS ; votre API est active ; la méthode d'authentification est celle attendue ; et le secret a été saisi correctement. Les échecs d'authentification n'apparaissent pas comme une erreur sur cet écran — ils se produisent au moment de la livraison.

Quelle est la différence entre « Durée maximale » et « Temps maximal » ? « Temps maximal » est le plus long intervalle entre deux tentatives. « Durée maximale » est le temps que IDCloud attend par tentative avant de la considérer comme un échec.

Ai-je besoin d'un webhook si j'interroge déjà le résultat via l'API ? Ce n'est pas obligatoire, mais cela évite à votre système d'avoir à interroger périodiquement. Si vous avez déjà une routine d'interrogation fonctionnelle, le webhook est une optimisation, pas une nécessité.

Référence rapide

Portail IDCloud
 └─ Paramètres (icône d'engrenage dans le menu latéral)
     └─ Onglet Webhook
         ├─ Informations client ....... URL client (Point de terminaison), HTTPS
         ├─ Authentification ........... Aucune | API Key | Basic Auth | OAuth 2.0
         │                              OAuth 2.0 : + URL d'authentification et Client ID
         └─ Tentatives de réessai (facultatif) ....... Tentatives maximales
                                       Limite de débit (req/s)
                                       Temps minimal (2 s) · Temps maximal (10 s)
                                       Durée maximale (2 s) · Doublements maximaux (5)

Un webhook par tenant et branche · UAT et Production indépendants · Secret jamais affiché · Annuler · Enregistrer