Configuration

Markdown

L'équipe Unico configure le webhook lors de l'onboarding de l'intégration.

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.

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": "humantoken"
}

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