Obtenir les résultats de vérification avec les webhooks
Didit ne vous envoie pas d'e-mail quand une vérification change de statut : configurez un webhook pour que votre backend en soit informé au moment même où cela se produit, et vérifiez la signature avant de lui faire confiance.
Un webhook est une requête HTTP que Didit envoie à votre URL quand quelque chose change. Ajoutez une destination sous API & Webhooks, souscrivez aux événements que vous voulez (il n'y a aucun caractère générique, listez-les tous), enregistrez le secret de signature, et vérifiez la signature avant de traiter quoi que ce soit.
Didit ne vous envoie pas d'e-mail quand une session passe en revue ou est refusée. Pour savoir au moment où un statut change, sans recharger la console, configurez un webhook : une URL sur votre serveur vers laquelle Didit envoie automatiquement la mise à jour.
Les webhooks sont le schéma d'intégration recommandé. Interroger périodiquement l'endpoint de décision fonctionne comme solution de repli, mais c'est plus lent, cela consomme plus de requêtes, et cela manque des événements qui ne sont livrés que par webhook : les modifications de données faites par un réviseur, les changements de statut de transaction, et les changements au niveau des entités.
#Le configurer
- Aller dans API & Webhooks
Dans la console de gestion, ouvrez l'application pour laquelle vous voulez recevoir des événements, puis allez dans API & Webhooks.
- Ajouter une destination
Donnez-lui un libellé, l'URL HTTPS publique de votre endpoint, et choisissez les événements que vous voulez recevoir : au minimum les changements de statut de session.
- Enregistrer le secret de signature
La destination vous montre un secret une seule fois. Enregistrez-le : votre serveur l'utilise pour confirmer qu'une requête vient bien de Didit et non d'un imposteur. Étapes de vérification complètes : Vérification de signature.
- Le tester
Utilisez Try Webhook sur la même page pour envoyer un événement de test entièrement formé (scénarios approuvé, refusé, en revue, KYB, entité et transaction) vers votre endpoint. Vous pouvez valider votre intégration de cette façon sans exécuter de vérification réelle.
- Add destination enregistre l'URL vers laquelle Didit envoie les résultats.
- Vérifiez chaque livraison avec ce secret de signature avant de lui faire confiance.
- Choisissez les événements qu'une destination reçoit.
- Test Webhook envoie une charge utile d'exemple pour que vous puissiez confirmer que votre endpoint l'accepte.
#Les événements auxquels vous pouvez souscrire
Il n'y a aucun caractère générique : listez chaque famille d'événements que vous voulez. Les répartir sur plusieurs destinations est possible et souvent plus propre.
| Événement | Se déclenche quand |
|---|---|
status.updated | Le statut d'une session KYC ou KYB change. Celui que vous voulez presque certainement |
data.updated | Les données de vérification sont modifiées après la création : un réviseur corrige un champ |
user.status.updated | Un utilisateur consolidé passe entre ACTIVE, FLAGGED et BLOCKED |
user.data.updated | Le profil, les compteurs ou les identifiants d'un utilisateur consolidé changent |
business.status.updated | Une entreprise consolidée change de statut |
business.data.updated | Les données d'une entreprise consolidée changent |
transaction.created | Une transaction est créée et son verdict initial est prêt |
transaction.status.updated | Le statut d'une transaction change par la suite |
travel_rule.status.updated | Le statut d'un échange Travel Rule change |
Il n'existe pas de session.status.updated ni de kyc.completed. Si vous vous
êtes abonné à un nom qui n'est pas dans cette liste, vous ne recevrez rien, et
cela ressemblera exactement à un échec de livraison. Vérifiez le nom d'abord.
#Ce que votre endpoint devrait faire
- Vérifier la signature avant tout le reste. Hachez avec HMAC le corps de requête brut, jamais une version re-sérialisée du JSON analysé, car re-sérialiser change les octets et la signature ne correspondra pas. Utilisez une comparaison en temps constant.
- Renvoyer un 2xx rapidement. Faites le travail lourd de façon asynchrone, après avoir répondu.
- Être idempotent. Basez-vous sur l'id de l'événement, ou sur id de session + statut + type de webhook. Les nouvelles tentatives et les doublons arrivent.
- Gérer chaque statut qui vous intéresse, y compris ceux qui arrivent longtemps après l'intégration : une session approuvée peut plus tard passer en revue via le monitoring AML continu.
- HTTPS uniquement. Les endpoints en HTTP simple ne sont pas pris en charge.
#Nouvelles tentatives
Sur un 5xx, un 404, un timeout, ou un échec de connexion, Didit réessaie deux fois :
- Première nouvelle tentative environ 1 minute après l'échec initial
- Deuxième nouvelle tentative environ 4 minutes plus tard
Après cela, la livraison est abandonnée. Chaque tentative est consignée séparément dans l'onglet Deliveries de la destination, donc vous pouvez voir exactement ce qui s'est passé plutôt que de deviner.
Deux nouvelles tentatives sur cinq minutes ne constituent pas une file d'attente durable. Si votre endpoint est indisponible pendant une heure, ces événements sont perdus. Réconciliez au démarrage en interrogeant l'endpoint de décision pour les sessions dont vous n'avez aucun statut final : les webhooks sont le chemin rapide, pas le seul chemin.
#Derrière un pare-feu ou un WAF
Didit livre depuis l'IP statique 18.203.201.92 avec un user agent DiditWebhook/2.0. Si votre périphérie bloque les clients inconnus (la posture par défaut de Cloudflare, par exemple), autorisez cette IP pour le nom d'hôte destinataire, sinon les livraisons échoueront avant d'atteindre votre code.
#Vous n'avez pas encore de backend ?
Vous pouvez toujours surveiller les résultats manuellement dans la section Verifications de la console pendant que vous en construisez un, ou utiliser un lien de vérification sans code en attendant.
#Prochaines étapes
- Quand un webhook n'arrive pas : quand un webhook n'arrive jamais
- Comprendre ce que signifie chaque statut une fois arrivé : ce que signifie chaque statut de session
- Référence technique complète, incluant des exemples de code de vérification de signature : Webhooks