Passer au contenu principal
À chaque verdict, VerifNer envoie un POST à vos endpoints avec l’événement verification.completed. Quand un humain tranche une vérification en revue, un second verification.completed part avec final_verdict renseigné.

Enregistrer un endpoint

Depuis la console, page Webhooks, ou par l’API :
  • L’URL doit être en HTTPS, vers une adresse publique : localhost, les adresses privées (10.x, 192.168.x…) et les noms internes sont refusés, et vérifiés à nouveau à chaque envoi. Pour recevoir les événements sur votre poste, relayez-les avec verifner listen --forward ou exposez votre serveur local avec un tunnel (cloudflared tunnel --url http://localhost:4000).
  • Le secret ne s’affiche qu’une fois : il sert à vérifier la signature.
  • Chaque endpoint reçoit les événements de son application (celle de la clé qui l’a créé, ou celle choisie dans la console), en test comme en live. Les champs data.app_id et data.mode vous disent lesquels.

L’événement

data est la vérification complète, comme dans la réponse de POST /v1/verify, avec mode et final_verdict en plus. Pour retrouver votre dossier, conservez l’id de la vérification, ou la reference passée à la session et lisible avec GET /v1/sessions/{id}. Les metadata passées à la session (ou à POST /v1/verify) reviennent dans data.metadata : null quand il n’y en a pas. Avec un flux, data.verdict est le verdict publié par le flux ; data.rules_verdict (le verdict des contrôles, seulement quand le flux l’a changé) et data.workflow (version, raison, équipe) disent ce qu’il a fait. Sans flux, les deux valent null.

workflow.notification

Un bloc Webhook de flux envoie à l’endpoint qu’il désigne un événement workflow.notification, avec la même enveloppe, les mêmes en-têtes, la même signature et les mêmes relances. data ne contient que les champs choisis dans le bloc :
Distinguez les deux types avec l’en-tête VerifNer-Event ou le champ type.

Vérifier la signature

L’en-tête VerifNer-Signature contient un horodatage t (secondes Unix) et v1, le HMAC-SHA256 en hexadécimal de la chaîne "<t>.<corps brut>", calculé avec le secret de l’endpoint.
Calculez le HMAC sur le corps brut reçu, avant tout parsing JSON. Re-sérialiser le JSON change les octets et la signature ne correspond plus.
Refusez un horodatage de plus de 5 minutes : cela empêche de rejouer un ancien événement intercepté.

Répondre et réessayer

  • Répondez avec un statut 2xx en moins de 10 secondes. Faites le travail lourd en arrière-plan.
  • Sans 2xx (erreur, délai dépassé, serveur injoignable), VerifNer réessaie avec un délai qui double à chaque fois, à partir d’une minute : 8 tentatives au total, sur environ quatre heures.
  • Un même événement garde le même id à chaque tentative. Traitez-le de façon idempotente : ignorez un id déjà traité.
  • Les événements peuvent arriver dans le désordre. Pour une vérification donnée, un événement avec final_verdict renseigné est toujours le plus récent.

Suivre les livraisons

GET /v1/webhooks/{id}/deliveries renvoie les 50 dernières livraisons d’un endpoint, avec leur état, le nombre de tentatives et la dernière erreur. La console les affiche aussi, page Webhooks. Pour supprimer un endpoint : DELETE /v1/webhooks/{id}.