Premiers pas

Chez Auco, afin de vous donner un contrôle total sur l'intégration de chaque processus créé, nous proposons un système de webhooks qui vous permet de recevoir des notifications à chaque étape de chaque flux de travail, du début à la fin.

Pour configurer le webhook, il existe deux méthodes : via l'API et via la plateforme web :

Création depuis app.auco.ai :

Vous devez être administrateur ou disposer des permissions d'administrateur pour effectuer cette configuration. Depuis la plateforme, vous ne pouvez créer qu'un seul webhook, qui sera le webhook « default ».

• Connectez-vous avec votre e-mail et votre mot de passe.
• Accédez à votre profil sur www.auco.ai/profile
• Entrez dans les options de développement
• En bas, vous trouverez les options pour modifier votre webhook et, si nécessaire, les en-têtes d'authentification.

Création via l'API d'Auco

Est-il possible d'avoir plusieurs webhooks ?

🆕 Oui ! Via l'API, vous pouvez créer plusieurs webhooks. Chaque webhook doit avoir un id. Votre premier webhook doit avoir l'id « default », où toutes les notifications seront envoyées par défaut ; les webhooks suivants peuvent avoir l'id de votre choix.

important

Pour définir quels webhooks recevront les notifications des états du processus, vous devez enregistrer la liste des ids de webhooks lors de la création du document.

Authentification

Incluez votre clé privée dans l'en-tête Authorization.

Authorization: prk_xxx...

Paramètres de création d'un webhook

Nom	Type	Description
id	String obligatoire	Nom identifiant du webhook ; le premier webhook doit être default.
description	String facultatif	Description de l'objectif du webhook.
url	String obligatoire	URL (URI valide) à laquelle les notifications du webhook seront envoyées.
header	Object facultatif	Objet { key, value } avec l'en-tête d'authentification à envoyer.
header.key	String conditionnel	Sous-champ de header. Obligatoire si header est envoyé : clé de l'en-tête.
header.value	String conditionnel	Sous-champ de header. Obligatoire si header est envoyé : valeur de l'en-tête.

Où sont-ils configurés ?

Les webhooks sont enregistrés via le endpoint Mettre à jour l'organisation (PUT /v1.5/ext/company), dans le paramètre webhooks. Vous y trouverez les exemples complets de requêtes en Curl, Python et Node.js.

👉 Consultez Mettre à jour l'organisation.

Envoyez toujours la liste complète

Le paramètre webhooks remplace la configuration existante : vous devez envoyer la liste complète et toujours inclure le webhook avec id: "default". Pour conserver les webhooks déjà créés, incluez-les dans la requête.

---

Signaux de la protection d'identité

Lorsque la validation d'identité d'un signataire ou d'un processus AucoFace passe par la protection d'identité d'Auco, la notification inclut le champ signals : la liste des signaux antifraude que la protection a enregistrés lors de cette validation.

"signals": [
  { "code": "ALERT_FACE", "severity": "ALERT" },
  { "code": "ALERT_EMAIL_CHANGED", "severity": "INFO" }
]

severity	Signification	A arrêté le processus
REPORT	Correspondance avec une liste de blocage.	Oui
ALERT	Alerte de fraude selon la configuration de votre organisation.	Oui
INFO	Signal informatif : il a été enregistré, mais n'a pas bloqué le processus.	Non

Décidez selon severity, pas selon code

La sévérité des codes ALERT_* dépend de la configuration de chaque organisation : un même code peut arriver en INFO ou en ALERT. Utilisez severity pour savoir si le signal a bloqué le processus.

signals est présent dans les notifications de signature (NOTIFICATION) et de blocage (BLOCKED) des documents et des packages, ainsi que dans toutes les notifications AucoFace. Il est absent lorsque la validation n'a jamais atteint la protection —par exemple, parce que la comparaison faciale a échoué en premier— et lorsque la liste est vide. Traitez un code que vous ne reconnaissez pas comme un signal supplémentaire : de nouveaux codes peuvent apparaître.

code	Signification
REPORT	La personne figure sur une liste de blocage.
REPORT_EMAIL	L'e-mail figure sur une liste de blocage.
REPORT_PHONE	Le téléphone figure sur une liste de blocage.
REPORT_FACE	Le visage figure sur une liste de blocage.
REPORT_DECEASED	La pièce d'identité appartient à une personne décédée.
REPORT_FACE_MISMATCH	Le visage ne correspond pas à celui enregistré.
ALERT_FACE	Le visage appartient à une autre personne enregistrée.
ALERT_IDENTITY_MISMATCH	Les données ne correspondent pas à l'état civil.
ALERT_IDENTIFICATION_NOT_FOUND	La pièce d'identité n'existe pas dans l'état civil.
ALERT_EMAIL_CHANGED	La personne utilise un e-mail différent de celui enregistré.
ALERT_PHONE_CHANGED	La personne utilise un téléphone différent de celui enregistré.
ALERT_EMAIL	L'e-mail est déjà associé à une autre personne.
ALERT_PHONE	Le téléphone est déjà associé à une autre personne.
ALERT_DEVICE	L'appareil a été utilisé par plusieurs personnes.
ALERT_IP	L'IP a été utilisée par plusieurs personnes.
ALERT_LOCATION	La localisation est inhabituelle pour cette personne.

---

Délai de réponse et nouvelles tentatives

Auco attend au maximum 10 secondes la réponse de votre endpoint. Si votre serveur ne répond pas dans ce délai, Auco ferme la connexion et la notification est enregistrée comme un délai d'attente dépassé.

Ces 10 secondes couvrent toute la requête : résolution DNS, négociation TLS et temps de réponse de votre serveur. Un endpoint qui met en moyenne 8 secondes est déjà à la limite.

Répondez d'abord, traitez ensuite

Renvoyez 200 dès que vous recevez la notification et mettez en file d'attente le travail lourd —écriture dans votre base de données, téléchargement du PDF, appel à un autre service— pour l'exécuter en arrière-plan.

Un gestionnaire qui télécharge des fichiers ou appelle un tiers de manière synchrone avant de répondre dépasse facilement les 10 secondes, et la notification est interrompue même si votre code s'est terminé correctement.

Nouvelles tentatives

Une notification est considérée comme livrée uniquement si votre endpoint répond avec un code 2xx. En cas d'échec —par délai dépassé, ou parce que vous répondez 4xx ou 5xx— Auco la renvoie jusqu'à 3 fois, en attendant un peu plus longtemps à chaque fois :

Tentative	Quand
1re	2 minutes après la tentative échouée
2e	4 minutes après la précédente
3e	6 minutes après la précédente

Après la troisième nouvelle tentative, Auco cesse d'essayer et cette notification est abandonnée : elle n'est plus renvoyée.

Un 4xx n'annule pas la notification

Répondre avec un code d'erreur n'indique pas à Auco d'abandonner l'événement : cela déclenche la même chaîne de nouvelles tentatives qu'un délai dépassé. Si votre intégration décide d'ignorer un status, répondez quand même 200 et écartez-le de votre côté.

Votre gestionnaire doit être idempotent

Une nouvelle tentative répète la même notification. Si votre serveur l'a traitée mais a répondu tardivement, vous la recevrez à nouveau. Utilisez le code du processus avec le status pour reconnaître une répétition, au lieu de créer un nouvel enregistrement à chaque livraison.

Le webhook n'est pas la seule voie

Une notification abandonnée n'étant jamais renvoyée, ne vous fiez pas uniquement au webhook pour connaître l'état d'un processus. Vous pouvez consulter son état à tout moment avec Consulter un processus.

---

⚠️ Réponses d'erreur

Code	Description
400	Webhook default manquant
401	Authentification invalide ou manquante