--- title: Webhook description: Configurez où IDCloud notifie votre système lorsqu'un parcours change d'état, comment il s'authentifie auprès de votre API, et ce qui se passe quand votre API ne répond pas. canonical: https://developer.unico.io/fr/dual-api/product-guide/portal-idcloud/settings/webhook locale: fr generated_by: markdown-export --- 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 à tous les types d'intégration. **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 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 de gestion de votre webhook, avec le bouton Configurer le webhook](/img/product-guide/webhook/en/01-manage-webhook.png) *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](/img/product-guide/webhook/en/02-edit-webhook.png) *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](/img/product-guide/webhook/en/02-edit-webhook.png) *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](/img/product-guide/webhook/en/02-edit-webhook.png) *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 ```text 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 ```