Aller au contenu principal

Webhook

Les articles GetProcess de cette documentation décrivent un moyen d'obtenir le statut d'un processus via un appel à un point de terminaison. De cette manière, un polling est effectué pour recevoir des informations sur les processus qui ont été créés. Cela signifie que le point de terminaison peut être appelé plusieurs fois pour le même processus afin d'obtenir le statut le plus récent.

Avec l'utilisation de webhooks, il est possible de notifier un point de terminaison spécifique chaque fois que le statut d'un processus change.

Qu'est-ce qu'un webhook ?​

Un webhook est un service de notification systémique qui permet une intégration asynchrone entre systèmes, où un système notifie l'autre via un déclencheur. Ainsi, les webhooks permettent de maintenir les systèmes à jour avec les informations les plus récentes sans nécessiter de polling constant pour vérifier les mises à jour.

Comment configurer le Webhook​

Pour configurer le webhook, les informations suivantes sont requises :

  • URL de notification : il s'agit du point de terminaison utilisé par Unico pour les notifications de mise à jour de statut.
  • Type d'authentification : il s'agit de la méthode utilisée pour authentifier l'invocation du point de terminaison. Les options suivantes sont disponibles :
    • OAuth2 ;
    • Basic Authorization ;
    • API Key ;
    • Aucune authentification.
  • Pour OAuth2, les informations suivantes doivent être fournies :
    • endpoint du Webhook ;
    • URL du fournisseur OAuth2 ;
    • ClientId du fournisseur OAuth2 ;
    • Secret du fournisseur OAuth2.
  • Pour Basic Authorization, il est nécessaire d'envoyer les informations au format user:pass.
  • Pour API Key, deux formats sont possibles :
    • header:value, lorsqu'un nom d'en-tête spécifique est souhaité ;
    • value, lorsque l'en-tête souhaité est Authorization.
  • Paramètres de nouvelle tentative : cela indique le nombre de tentatives en cas d'échec lors de l'appel du point de terminaison :
    • Nombre maximum de tentatives ;
    • Intervalle entre les tentatives (en secondes) ;
    • Limite de débit : nombre maximum d'envois simultanés (max : 500) ;
    • Délai d'expiration : temps d'attente maximum pour la réponse du point de terminaison (en secondes).
  • Statuts à notifier : vous pouvez vous abonner à des statuts spécifiques pour recevoir des notifications. Ceux-ci incluent :
    • approved : transaction approuvée ;
    • processing : transaction en cours de traitement ;
    • inconclusive : nous n'avons pas pu effectuer une validation concluante ;
    • shared : transaction partagée, en attente de soumission ;
    • skipped : la personne a ignoré la capture biométrique dans le flux ;
    • unknown-share : la personne a indiqué ne pas reconnaître l'achat ;
    • absent-holder : le titulaire de la carte n'est pas présent pour effectuer la capture ;
    • expired : la personne n'a pas terminé la capture dans le délai établi et la transaction a expiré.
À propos de l'authentification

L'API peut être protégée par une méthode d'authentification telle que Basic Authentication ou API Key. Une liste d'IP valides pour l'accès peut également être définie pour une protection supplémentaire.

Intégration avec Vérification sans carte présente​

Lors de la configuration d'un webhook sur la plateforme, vous pouvez recevoir des informations sur les processus via des notifications envoyées à un point de terminaison de l'API que vous avez développée pour recevoir ces mises à jour.

Les informations envoyées par la plateforme à l'API incluent :

  • ID : identifiant de la transaction ;
  • Status : statut de la transaction ;
  • HasIdentityChanged : indique si un changement d'identité s'est produit dans la transaction (optionnel).
remarque

Notez qu'il est possible de choisir les statuts pour lesquels le client souhaite être notifié via la configuration du webhook. Après l'envoi de ces informations, la réponse attendue doit être synchrone.

Requêtes​

La requête doit être une méthode POST vers une API REST, ce qui la rend plus simple et plus sécurisée pour envoyer les informations. Tous les champs doivent être obligatoires. Le corps de la requête doit accepter l'identifiant et le statut de la transaction, comme illustré dans l'exemple suivant :

{
  "id": "8263a268-5388-492a-bca2-28e1ff4a69f0",
  "status": "approved",
  "hasIdentityChanged": false
}

Réponse​

La réponse doit être synchrone. Le statut des requêtes réussies doit être compris entre 200 et 299. Tout autre statut sera considéré comme un échec, et Vérification sans carte présente effectuera des tentatives de notification supplémentaires (avec un backoff exponentiel entre elles), jusqu'à recevoir une réponse 2xx ou atteindre le nombre maximum de tentatives.

Statut de la réponse​

Actuellement, nous disposons d'un ensemble de statuts, mais cet ensemble peut évoluer à l'avenir. Il est donc recommandé de rendre configurables les statuts qui intéressent le client afin d'agir en conséquence. Par exemple, si l'intention est d'agir chaque fois qu'une capture est réalisée avec succès, cela correspond actuellement au statut « processing ». Cependant, comme cela pourrait être modifié à l'avenir, il est recommandé que le statut indiquant une capture réussie soit configurable dans le système, afin qu'un futur changement vers le statut « captured » puisse être facilement mis en œuvre.

De plus, nous recommandons d'avoir des actions spécifiques pour des statuts spécifiques et une action générale au cas où le statut serait inconnu (par exemple, en supposant que tout ce qui est différent de « processing » et « approved » est inconclusif). Ceci est important car de nouveaux statuts peuvent apparaître à l'avenir, et il n'est pas prévu que le webhook cesse de fonctionner à cause de cela.

Points importants à considérer​

Portez attention aux aspects suivants lors du développement de l'API que Vérification sans carte présente utilisera pour notifier les changements de statut :

Limite de débit — afin d'éviter de surcharger vos ressources dans des situations impliquant de nombreuses transactions, il est possible de spécifier une limite supérieure au nombre de fois où le point de terminaison peut être invoqué.

Taux d'erreur — le taux d'erreur (réponses en dehors de la plage [200, 299]) doit toujours être maintenu bas. Sinon, le débit du webhook sera automatiquement réduit, et cette réduction, combinée au mécanisme de nouvelle tentative, peut entraîner une augmentation du temps d'exécution des nouveaux webhooks.

Idempotence — l'implémentation actuelle du webhook garantit une livraison au moins une fois (« at-least-once »), de sorte que le même statut peut être notifié plus d'une fois. Par conséquent, l'implémentation du point de terminaison doit être réalisée de manière idempotente.

Solution de repli (Fallback) — en cas d'indisponibilité du service de webhook, il est recommandé de mettre en place une méthode de secours afin de pouvoir continuer à récupérer les statuts des transactions dans le délai de réponse établi. La requête vers le point de terminaison est décrite dans la section Référence API de cette documentation.

Dernière mise à jour le