Aller au contenu principal

Configuration

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.

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

Informations requises​

ChampDescription
URL de notificationEndpoint qu'Unico appellera pour livrer les notifications d'événements. Doit être accessible via HTTPS.
Type d'authentificationLa façon dont Unico s'authentifie auprès de votre endpoint. Voir les options ci-dessous.
Paramètres de nouvelles tentativesNombre maximum de tentatives et intervalle entre les tentatives (le backoff exponentiel est appliqué).
Limite de concurrenceNombre maximum de livraisons simultanées en cours (max : 500).
Délai d'attenteTemps d'attente maximum pour la réponse de l'endpoint, en secondes.
Statuts à notifierL'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 :

ÉtatDescription
PROCESS_STATE_FINISHEDProcessus terminé — état terminal, quel que soit le résultat.
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.

{
  "processId": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "state": "PROCESS_STATE_FINISHED",
  "flow": "id"
}
lastEvent et lastEventDescription

Ces deux champs apparaissent dans le payload uniquement lorsque result = expired — c'est-à-dire 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 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.
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é.

Dernière mise à jour le