À 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.
http://localhost est accepté pour vos tests.
- Le
secret ne s’affiche qu’une fois : il sert à vérifier la signature.
- Chaque endpoint reçoit les événements de votre organisation, en test comme en live. Le champ
data.mode vous dit lequel.
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}.
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}.