---
title: Configuration
description: Guide étape par étape pour configurer les webhooks IDCloud — libre-service via le portail pour les intégrations Web et SDK, et configuration par client pour les intégrations API utilisant l'orchestration Check (Brésil uniquement).
canonical: https://developer.unico.io/fr/dual-api/developers/webhooks-and-events/setup
locale: fr
generated_by: markdown-export
---

IDCloud prend en charge deux modalités de webhook, selon la façon dont vous intégrez :

- **Via le portail** — pour les intégrations Web et SDK. Configuration en libre-service directement dans le portail IDCloud.
- **Par client** — pour les intégrations API utilisant la capacité **d'orchestration Check** (un flux asynchrone). Configuré par l'équipe Unico. Disponible **au Brésil uniquement**.

### Via le portail (Web & SDK)

Pour enregistrer ou mettre à jour votre endpoint de webhook, accédez au portail IDCloud et naviguez vers **Paramètres > Webhook**.

#### Informations requises

| Champ | Description |
|---|---|
| **URL de notification** | Endpoint qu'Unico appellera pour livrer les notifications d'événements. Doit être accessible via HTTPS. |
| **Type d'authentification** | La façon dont Unico s'authentifie auprès de votre endpoint. Voir les options ci-dessous. |
| **Paramètres de nouvelles tentatives** | Nombre maximum de tentatives et intervalle entre les tentatives (le backoff exponentiel est appliqué). |
| **Limite de concurrence** | Nombre maximum de livraisons simultanées en cours (max : **500**). |
| **Délai d'attente** | Temps d'attente maximum pour la réponse de l'endpoint, en secondes. |
| **Statuts à notifier** | L'ensemble des états de processus qui déclenchent une notification. Actuellement fixé à `PROCESS_STATE_FINISHED` ; non configurable pour le moment. |

#### Méthodes d'authentification

****OAuth2****

Fournir :

  - `endpoint` du webhook
  - `URL` du fournisseur OAuth2
  - `ClientId` du fournisseur OAuth2
  - `Secret` du fournisseur OAuth2

  Unico demandera un token d'accès à l'URL du fournisseur en utilisant les identifiants client et le transmettra à votre endpoint en tant que token Bearer.

****Autorisation de base****

Fournissez les identifiants au format `user:pass`. Unico les encode en Base64 et les envoie dans l'en-tête `Authorization: Basic <encoded>` à chaque appel de webhook.

****Clé API****

Deux formats sont pris en charge. La chaîne est divisée au niveau du **premier** deux-points :

  - `header:value` — définit un nom d'en-tête personnalisé. Exemples :
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` uniquement (sans deux-points) — la valeur est envoyée dans l'en-tête `Authorization` sans préfixe de schéma. Exemple : `abc123` → `Authorization: abc123`.

  Utilisez le format `header:value` lorsque vous avez besoin d'un schéma Bearer (p. ex. `Authorization:Bearer <token>`) ; le format valeur seule envoie la valeur brute sans préfixe.

****Sans authentification****

Aucun identifiant n'est envoyé. Recommandé uniquement pour les environnements de développement — les endpoints de production doivent toujours requérir une authentification.

#### États de processus déclenchant des notifications

Actuellement, Unico envoie une notification chaque fois qu'un processus passe à l'état :

| État | Description |
|---|---|
| `PROCESS_STATE_FINISHED` | Processus terminé — état terminal, quel que soit le résultat. |

:::warning[Les états peuvent évoluer]
L'ensemble des états notifiés par la plateforme peut changer à l'avenir. Rendez les états auxquels réagit votre endpoint **configurables**, afin que l'ajout d'un nouvel état ne nécessite pas de redéployer votre service.
:::

#### Format de la requête

Les livraisons de webhooks sont des requêtes **POST** vers votre endpoint. Le corps contient l'identifiant du processus et l'état actuel.

```json
{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
```

:::note[`lastEvent` et `lastEventDescription`]
Ces deux champs apparaissent dans le payload **uniquement lorsque le processus a expiré** avant que l'utilisateur termine le parcours. Ils sont absents des payloads de complétion normaux. Consultez [Types d'événements](/developers/webhooks-and-events/event-types) pour le schéma complet et la liste des valeurs `lastEvent` possibles.
:::

#### Réponse attendue

Votre endpoint doit répondre **de manière synchrone** :

- **Succès** : tout statut HTTP dans la plage `200`–`299`.
- **Échec** : tout autre statut. Unico effectuera de nouvelles tentatives avec backoff exponentiel jusqu'au nombre maximum de tentatives configuré, ou jusqu'à la réception d'un `2xx`.

:::tip[Répondez rapidement]
Accusez réception du webhook rapidement (avant votre délai d'attente configuré) et traitez le payload de manière asynchrone de votre côté. Un traitement long dans le gestionnaire de webhook augmente le risque de délais d'attente dépassés et de nouvelles tentatives inutiles.
:::

Pour les conseils sur l'idempotence et la gestion des nouvelles tentatives, voir [Sécurité](/developers/webhooks-and-events/security).

### Par client (API — Brésil uniquement)

:::info[Brésil uniquement]
Le webhook par client est disponible exclusivement pour les intégrations API au Brésil qui utilisent la capacité **d'orchestration Check** — un flux asynchrone où le résultat du processus est livré via webhook plutôt que comme réponse API synchrone.
:::

Pour enregistrer ou mettre à jour votre endpoint, contactez votre équipe **CS / Onboarding**.

#### Informations requises

| Champ | Description |
|---|---|
| **URL de notification** | Endpoint que votre système expose pour recevoir les mises à jour de statut. Doit être accessible via HTTPS. |
| **Type d'authentification** | La façon dont Unico s'authentifie auprès de votre endpoint. Voir les options ci-dessous. |
| **Paramètres de nouvelles tentatives** | Nombre maximum de tentatives et intervalle entre les tentatives (le backoff exponentiel est appliqué). |
| **Limite de concurrence** | Nombre maximum de livraisons simultanées en cours (max : **500**). |
| **Délai d'attente** | Temps d'attente maximum pour la réponse de l'endpoint, en secondes. |

#### Méthodes d'authentification

****OAuth2****

Fournir :

  - `endpoint` du webhook
  - `URL` du fournisseur OAuth2
  - `ClientId` du fournisseur OAuth2
  - `Secret` du fournisseur OAuth2

  Unico demandera un token d'accès à l'URL du fournisseur en utilisant les identifiants client et le transmettra à votre endpoint en tant que token Bearer.

****Autorisation de base****

Fournissez les identifiants au format `user:pass`. Unico les encode en Base64 et les envoie dans l'en-tête `Authorization: Basic <encoded>` à chaque appel de webhook.

****Clé API****

Deux formats sont pris en charge. La chaîne est divisée au niveau du **premier** deux-points :

  - `header:value` — définit un nom d'en-tête personnalisé. Exemples :
    - `X-API-Key:abc123` → `X-API-Key: abc123`
    - `Authorization:Bearer abc123` → `Authorization: Bearer abc123`
  - `value` uniquement (sans deux-points) — la valeur est envoyée dans l'en-tête `Authorization` sans préfixe de schéma. Exemple : `abc123` → `Authorization: abc123`.

  Utilisez le format `header:value` lorsque vous avez besoin d'un schéma Bearer (p. ex. `Authorization:Bearer <token>`) ; le format valeur seule envoie la valeur brute sans préfixe.

****Sans authentification****

Aucun identifiant n'est envoyé. Recommandé uniquement pour les environnements de développement — les endpoints de production doivent toujours requérir une authentification.

#### Codes de statut

Le webhook par client utilise des **codes de statut numériques** :

| Code | Description |
|---|---|
| `2` | Divergence — le processus s'est terminé avec une divergence dans la vérification d'identité. |
| `3` | Terminé — le processus s'est terminé avec succès. |
| `5` | Erreur — le processus s'est terminé en raison d'une erreur. |

#### Format de la requête

Les livraisons de webhooks sont des requêtes **POST** vers votre endpoint. Le corps contient l'identifiant de la transaction et le code de statut numérique.

```json
{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": 3
}
```

#### Réponse attendue

Votre endpoint doit répondre **de manière synchrone** :

- **Succès** : tout statut HTTP dans la plage `200`–`299`.
- **Échec** : tout autre statut. Unico effectuera de nouvelles tentatives avec backoff exponentiel jusqu'au nombre maximum de tentatives configuré, ou jusqu'à la réception d'un `2xx`.

:::tip[Répondez rapidement]
Accusez réception du webhook rapidement (avant votre délai d'attente configuré) et traitez le payload de manière asynchrone de votre côté. Un traitement long dans le gestionnaire de webhook augmente le risque de délais d'attente dépassés et de nouvelles tentatives inutiles.
:::

:::warning[Livraison au moins une fois]
La plateforme garantit une livraison au moins une fois — la même notification peut arriver plusieurs fois. Implémentez l'idempotence de votre côté en utilisant le champ `id` pour gérer les doublons en toute sécurité.

Pour les conseils sur l'idempotence et la gestion des nouvelles tentatives, voir [Sécurité](/developers/webhooks-and-events/security).
:::