Webhooks
Où les résultats sont livrés, quels événements vont où, et les avertissements qui signalent que personne n'écoute
Un point de terminaison webhook est une URL à vous vers laquelle nous envoyons des événements au fil des vérifications. C'est ainsi que vos propres systèmes apprennent le résultat sans avoir à nous interroger en boucle.
Enregistrer un point de terminaison est le travail de la personne qui gère vos serveurs. Lire cette page pour comprendre pourquoi quelque chose n'est pas arrivé est à la portée de tous.
Enregistrer un point de terminaison
Donnez-nous une URL HTTPS que vous contrôlez. Nous y envoyons des contenus d'événements signés. L'environnement est fixé à l'enregistrement du point de terminaison et ne peut plus être modifié ensuite : un point de terminaison sandbox reste donc un point de terminaison sandbox pour toujours.
La description facultative est votre propre libellé. Elle vaut la peine d'être renseignée, car le routage par clé rend tout à fait ordinaire d'avoir deux points de terminaison sur le même hôte, et c'est le nom qui permet de les distinguer dans la liste.
Le secret de signature est affiché une fois à la création du point de terminaison, et une fois encore si vous le renouvelez. Le renouvellement le remplace immédiatement, sans période de chevauchement : les livraisons échouent donc à la vérification de signature de votre côté jusqu'à ce que le nouveau secret soit déployé. Ces deux actions demandent un code de votre application d'authentification.
Choisir les événements
Un point de terminaison ne reçoit que les événements auxquels il est abonné. Les plus courants :
| Événement | Quand il se déclenche |
|---|---|
verification.created | Une session a été créée |
verification.approved | Le verdict est approuver |
verification.rejected | Le verdict est rejeter |
verification.review | Le verdict est réviser, et une personne doit l'examiner |
verification.expired | Le demandeur n'a jamais terminé la session à temps |
verification.corrected | Un résultat que nous vous avions déjà envoyé était faux, et a été corrigé |
verification.data_updated | Quelqu'un de votre équipe a modifié les données du demandeur. Le résultat ne change pas ; récupérez de nouveau la vérification pour obtenir les nouvelles valeurs |
verification.completed | La session a atteint un état final, quel que soit le résultat |
Un nouveau point de terminaison démarre avec approuvé, rejeté, réviser, expiré et
verification.data_updated déjà cochés, et vous pouvez modifier la sélection avant d'enregistrer.
Chaque point de terminaison qui existait avant que les données des demandeurs puissent être modifiées,
et qui était abonné à au moins un événement, a reçu verification.data_updated automatiquement.
Le catalogue complet, avec les contenus, se trouve dans Webhook events.
Ne vous abonnez pas à la fois à completed et aux événements propres à chaque verdict
verification.completed se déclenche en même temps que les événements de verdict, si bien que choisir
les deux livre chaque résultat deux fois. Le sélecteur vous avertit lorsque vous êtes sur le point de
le faire.
Un point de terminaison abonné à rien ne reçoit rien, et la liste le dit clairement. Elle le dit aussi pour un point de terminaison abonné à un nom d'événement que plus rien n'envoie.
Routage par clé API
Chaque événement est rapproché de la clé API qui a créé la session : c'est ainsi qu'un compte qui regroupe plusieurs activités envoie les résultats de chacune vers son propre système.
Un point de terminaison est soit réglé sur toutes les clés API, c'est-à-dire chaque vérification de cet environnement, y compris les sessions créées sans clé, soit limité à des clés nommées.
La console surveille les deux façons dont cela peut mal tourner et vous prévient avant vos clients.
Une clé que rien ne reçoit. Créer une clé API ne l'abonne à rien : les vérifications créées avec elle ne vont nulle part tant que vous ne l'ajoutez pas à un point de terminaison ou que vous ne réglez pas un point de terminaison sur toutes les clés.
Rien ne reçoit les sessions sans clé. Une vérification lancée depuis cette console ne porte aucune clé API, elle n'atteint donc qu'un point de terminaison réglé sur toutes les clés. Si chaque point de terminaison est limité à des clés nommées, ces sessions ne sont livrées nulle part.
Tester avant de s'y fier
Envoyer un événement de test envoie immédiatement un contenu d'exemple au point de terminaison, signé avec son secret actuel. Il ne concerne personne : les identifiants qu'il contient sont manifestement faux et l'enveloppe est marquée comme test, pour que votre gestionnaire puisse la distinguer du trafic réel. Pour le reste, le corps correspond à ce que nous envoyons pour de vrai, si bien qu'un gestionnaire qui accepte le test accepte aussi le réel.
Un court délai d'attente s'applique entre deux tests.
Suivre les livraisons
Chaque point de terminaison dispose d'un panneau montrant le trafic récent : tout accepté, rien en attente, rien renvoyé, ou les échecs s'il y en a. Il indique clairement quand rien n'a été envoyé du tout.
L'historique des livraisons provient des journaux d'intégration : un rôle sans accès aux Journaux voit donc le point de terminaison mais pas ses contenus. Cette limite existe parce qu'un contenu enregistré est une copie mot pour mot de ce que nous avons envoyé au sujet d'un demandeur.
Pour l'historique complet, les filtres et la possibilité de renvoyer une livraison précise, allez dans Journaux.
Désactiver et supprimer
Désactiver interrompt les livraisons jusqu'à ce que vous le réactiviez, ce qui convient pendant une maintenance de votre côté. Supprimer est définitif, et nous cessons complètement d'envoyer vers cette URL.
Aucune de ces actions ne fait perdre les vérifications. Les événements qui n'ont pas pu être livrés sont réessayés, et une livraison peut ensuite être renvoyée à la main.
Être prévenu en cas de panne
Ajoutez des adresses d'alertes développeur dans Paramètres et nous leur écrirons lorsque votre intégration perd un événement. Les alertes concernant un même point de terminaison sont regroupées, si bien qu'une panne donne un seul message plutôt qu'un par événement perdu. Sans ces adresses, personne n'est prévenu.