Verify API Webhooks

Introduction

Crochets Web sont une extension d'une API - au lieu que votre code demande des données à notre plateforme API, Vonage vous envoie les données par le biais d'une demande Web à votre application. Le webhook de l'API Verify reçoit des mises à jour de l'état de vos demandes, et sera le résultat d'un appel API antérieur - ce type de webhook est également appelé "callback".

Réception de webhooks

Pour permettre aux serveurs Vonage d'envoyer des données à votre application via les webhooks, vous devez configurer un serveur web pour recevoir les requêtes HTTP entrantes. Vous devez également spécifier l'URL de chaque webhook sur votre serveur web afin que les données puissent être envoyées à chacun d'entre eux.

Pour commencer à utiliser les webhooks de Verify :

  1. Créez un Account Vonage.
  2. Rédigez des scripts pour traiter les informations envoyées ou demandées par Vonage. Votre serveur doit répondre par un 200 ou 204 La réponse HTTP, autre qu'un 2xx fera en sorte que les serveurs de Vonage tentent à nouveau de livrer le rappel.
  3. Publiez vos scripts en les déployant sur un serveur. Pour un développement local, essayez Ngrok.
  4. Configurez votre point de terminaison Verify webhook.
  5. Entreprendre une action (telle que envoi d'une demande de vérification par SMS) qui déclenchera ce webhook.

Les informations relatives à votre demande sont ensuite envoyées à votre point de terminaison webhook.

Configurez les URL de votre webhook Verify

L'API Verify prend en charge un webhook d'état, qui est configuré dans votre paramètres de l'application dans le tableau de bord du développeur :

Webhooks can be configured on the customer dashboard

Cette fonction est utilisée pour envoyer des mises à jour d'état (par exemple, des événements de progression ou d'achèvement) pour vos demandes de Verify.

Tester les webhooks localement

Afin de tester le bon fonctionnement des webhooks sur votre application exécutée localement, vous devrez créer un tunnel sécurisé entre Vonage et votre application. Vous pouvez le faire à l'aide d'une application de tunnel sécurisé telle que Ngrok. Voir Tester avec Ngrok pour plus d'informations.

Webhooks signés

Les webhooks Verify sont signés par défaut. Les webhooks signés permettent à votre application de vérifier qu'une demande provient bien de Vonage et que sa charge utile n'a pas été altérée pendant le transit. Lorsqu'il reçoit une demande, le webhook entrant inclut un jeton JWT dans l'en-tête d'autorisation qui est signé avec votre secret de signature.

Pour plus d'informations sur le décodage des webhooks signés, voir ici.

Types de rappels

Rappel d'événements

Un webhook d'événements entrants. Il affichera le résultat final de votre demande en utilisant la balise status domaine :

  • completed - la demande est terminée et l'utilisateur a été vérifié avec succès.
  • blocked - la demande a été bloquée en raison des règles de vélocité, ou le numéro fourni est un VOIP.
  • failed - la demande a échoué car le numéro donné n'était pas un numéro valide.
  • expired - la demande n'a pas été traitée dans le délai imparti.
  • user_rejected - l'utilisateur a introduit un code PIN incorrect.
  • cancelled - l'utilisateur a annulé la demande avant d'avoir terminé le processus d'authentification.
  • action_pending - l'utilisateur n'a rien fait pour lancer la procédure d'authentification. Par exemple, l'utilisateur check_url que l'utilisateur reçoit pour commencer l'authentification silencieuse n'a pas encore eu lieu.
{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "sms",
   "status": "completed",
   "finalized_at": "2020-01-01T14:00:00.000Z",
   "client_ref": "my-personal-ref"
}

Authentification silencieuse

Dans le cadre d'un Authentification silencieuse vous recevrez un rappel d'événement à votre webhook - par exemple :

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "action": [
      {
         "type": "check",
         "check_url": "https://eu.api.silent.auth/phone_check/v0.1/checks/:request_id/redirect"
      }
   ]
}

Rappel du résumé

Les rappels de synthèse contiennent une mise à jour de l'état d'une demande particulière. Comme vous pouvez le voir dans l'exemple ci-dessous, il y a deux champs Status - le premier est le statut de la demande globale, et les autres montrent le résultat de chaque canal utilisé dans le flux de travail.

Pour la demande, il existe six valeurs de statut différentes :

  • completed - la demande est terminée et l'utilisateur a été vérifié avec succès.
  • failed - la demande a échoué car le numéro indiqué n'était pas un numéro valide ou n'était pas une IP mobile.
  • expired - la demande n'a pas été traitée dans le délai imparti.
  • user_rejected - l'utilisateur a saisi trois fois un code PIN incorrect, ce qui a interrompu le processus.
  • blocked - la demande a été bloquée en raison des règles de vélocité, ou le numéro fourni est un VOIP.
  • cancelled - l'utilisateur a annulé la demande avant d'avoir terminé le processus d'authentification.

Dans le flux de travail, il y a sept valeurs de statut différentes que vous pouvez voir lorsque vous utilisez l'API :

  • unused - le canal n'a pas été utilisé car la demande a été convertie par un canal précédent dans le flux de travail.
  • completed - le canal a été utilisé, ce qui a permis une vérification réussie.
  • failed - un canal défini dans le flux de travail a échoué parce que le numéro donné n'était pas un numéro valide ou n'était pas une IP mobile, ou parce que le pays dans lequel se trouvait l'utilisateur n'est pas couvert par Verify.
  • expired - tout canal défini dans le flux de travail a expiré car l'OTP n'a pas été saisi dans le délai imparti.
  • blocked - Le canal SMS/Voix a été bloqué en raison des règles de vélocité.
  • user_rejected - l'utilisateur a saisi à trois reprises un code PIN incorrect, ce qui a mis fin au flux de travail pour le canal utilisé.
  • cancelled- le processus d'authentification d'un canal spécifique défini dans le flux de travail a été annulé alors qu'il était encore en cours.

Cet exemple montre une mise à jour pour une demande de vérification terminée. Le premier canal a tenté d'utiliser les SMS, mais la demande a expiré. Ensuite, WhatsApp a été utilisé et l'utilisateur a été vérifié avec succès. Le canal vocal n'ayant pas été tenté, le statut est le suivant unused.

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "submitted_at": "2020-01-01T14:00:00.000Z",
   "status": "completed",
   "type": "summary",
   "channel_timeout": 300,
   "workflow": [
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:02:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T15:05:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

Pour compléter la demande d'authentification silencieuse, vous devez lire le fichier check_url et le transmettre au client pour qu'il s'authentifie.