Fonctionnement des webhooks
Lorsqu’un événement déclencheur se produit, Youverify envoie une requête HTTPPOST à l’URL que vous avez configurée. Le corps de la requête est un objet JSON décrivant l’événement. Votre endpoint doit répondre avec le code HTTP 200 dans un délai raisonnable ; toute autre réponse amène Youverify à réessayer la livraison.
Les webhooks sont des communications de serveur à serveur. Votre endpoint de webhook doit être accessible publiquement via HTTPS et ne doit exiger aucune authentification du client.
Enregistrer votre endpoint de webhook
1
Ouvrir le tableau de bord Cowork
Connectez-vous à cowork.youverify.co et accédez à Settings → API KEY / Webhook.
2
Définir votre URL de rappel
Faites défiler jusqu’à la section Webhook et saisissez votre URL de rappel HTTPS. Il s’agit de l’endpoint sur lequel Youverify enverra un
POST pour chaque événement.3
Enregistrer et tester
Enregistrez la configuration. Vous pouvez envoyer un événement de test depuis le tableau de bord pour vérifier que votre endpoint est accessible et renvoie
200.Structure de la charge utile du webhook
Chaque webhook envoyé par Youverify partage la même enveloppe de premier niveau :string
Le nom de l’événement, séparé par des points, par exemple
identity.verification.completed ou tm.alert.created.string
La version de l’API qui a produit cet événement. Actuellement
v1 (KYT) ou v2 (KYC).object
La charge utile complète de l’événement. Sa structure varie selon le type d’événement : consultez les pages dédiées à chaque événement pour plus de détails.
number | string
Horodatage de l’événement. Les événements KYT utilisent un entier epoch Unix ; les événements KYC utilisent une chaîne ISO 8601.
Accuser réception
Renvoyez le code HTTP200 dès que vous recevez le webhook, avant tout traitement. Si Youverify ne reçoit pas de réponse 200, il réessaiera la livraison. Gardez votre gestionnaire rapide : écrivez la charge utile dans une file d’attente et traitez-la de manière asynchrone.
Valider les signatures des webhooks
Youverify signe chaque charge utile de webhook avec votre clé secrète afin que vous puissiez confirmer que la requête provient bien de Youverify. La signature est envoyée dans l’en-tête de requêtex-yv-signature sous la forme d’un condensé hexadécimal HMAC-SHA256 du corps brut de la requête.
Vérifiez la signature avant de traiter tout événement :
Catégories d’événements
Les webhooks Youverify sont regroupés en quatre catégories. Chaque catégorie dispose de sa propre page dédiée :Événements KYC
Événements de vérification d’identité terminée et de vérification d’adresse terminée.
Événements KYT / Transactions
Événements d’évaluation de transaction démarrée, d’évaluation terminée et de transaction mise à jour.
Événements d'alerte
Événements d’alerte créée, de triage d’alerte créé et d’alerte mise à jour, émis par le moteur de surveillance des transactions.
Événements Client / Évaluation
Événements de client créé, de client mis à jour et de cycle de vie des évaluations provenant du service KYT.
Comportement des nouvelles tentatives
Si votre endpoint renvoie une réponse autre que200 ou ne répond pas dans le délai imparti, Youverify réessaiera la livraison. Concevez votre gestionnaire de manière idempotente : utilisez le champ eventId (présent sur les événements KYT) ou le champ data.id / data.verificationId pour détecter et ignorer en toute sécurité les livraisons en double.
Le statut
PENDING d’une vérification d’identité indique qu’un fournisseur d’identité en amont est temporairement indisponible. Lorsque la vérification est terminée, Youverify transmet le résultat par webhook. Écoutez toujours le webhook plutôt que de considérer qu’une réponse PENDING est définitive.