---
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/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 cinq 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 |
| **mTLS** | Certificat client, Clé privée, AC du serveur (facultatif) | Votre API n'accepte que les appels de clients qui présentent un certificat (TLS mutuel). IDCloud présente le certificat que vous fournissez à chaque notification |

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.*

#### Configurer mTLS

Avec **mTLS**, IDCloud s'identifie auprès de votre API en présentant un certificat client (TLS
mutuel), au lieu d'envoyer une clé, un mot de passe ou un jeton. Votre API doit être configurée
pour demander ce certificat et pour faire confiance à son émetteur. Sélectionner **mTLS** affiche
trois champs :

| Champ | Ce qu'il faut fournir |
| :- | :- |
| **Certificat client (PEM)** | La chaîne de certificats au format PEM, certificat feuille en premier. Ajoutez les certificats intermédiaires après le vôtre, afin que votre API puisse rattacher le certificat à une autorité à laquelle elle fait confiance |
| **Clé privée (PEM)** | La clé associée au certificat, au format PEM et **sans mot de passe**. Elle est stockée chiffrée et n'est plus jamais affichée |
| **AC du serveur (PEM, facultatif)** | Uniquement si le certificat de votre API est signé par une autorité de certification privée. Sans ce champ, IDCloud fait confiance aux autorités de certification publiques |

Vous pouvez choisir un fichier `.pem` ou coller le texte. Chaque champ accepte jusqu'à 20 000
caractères.

Quelques règles à connaître avant de choisir mTLS :

- **L'URL doit être en HTTPS**, et votre API doit accepter TLS 1.2 ou une version plus récente.
- **Une fois enregistré, le type est verrouillé.** Le type d'authentification ne peut pas être
  remplacé par un autre sur cet écran. Pour changer de méthode, contactez le support Unico.
- **Aucun autre identifiant n'est envoyé.** mTLS ne peut pas être combiné avec API Key, Basic Auth
  ou OAuth 2.0 sur le même webhook.
- **Les redirections comptent comme des échecs.** IDCloud ne les suit pas, donc faites pointer
  l'URL vers l'adresse finale.

### É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. Avec mTLS, il valide plutôt le certificat et la clé : les deux doivent être au format PEM, la
clé ne doit pas avoir de mot de passe et doit correspondre au certificat, et le certificat doit
être dans sa période de validité.

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 remplacer le certificat mTLS avant son expiration ?** Modifiez le webhook. Le certificat
et la clé privée apparaissent masqués. Fournissez le nouveau certificat **et** la nouvelle clé
privée — les deux sont obligatoires, même si un seul des deux a changé — ainsi que l'AC du
serveur, à nouveau, si vous en utilisez une. Enregistrez ensuite. IDCloud commence à utiliser le
nouveau certificat dans un délai d'environ 5 minutes ; gardez donc l'ancien certificat valide un
peu plus longtemps que ce délai avant de le révoquer. Si vous ne modifiez aucun des trois champs,
le certificat actuel continue d'être utilisé.

**Puis-je passer de mTLS à un autre type d'authentification ?** Pas sur cet écran : après
l'enregistrement, le type est verrouillé. Contactez le support Unico pour retirer la configuration
du webhook, puis créez-la à nouveau avec la nouvelle méthode.

**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. Avec mTLS, vérifiez aussi que votre API fait confiance à
l'émetteur du certificat, que le certificat n'a pas expiré, et que l'AC du serveur est renseignée
si le certificat de votre API provient d'une autorité de certification privée. 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 | mTLS
         │                              OAuth 2.0 : + URL d'authentification et Client ID
         │                              mTLS : + Certificat client, Clé privée, AC du serveur (facultatif)
         └─ 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
```