Verificar los Webhooks de la API

Introducción

Webhooks son una extensión de una API: en lugar de que tu código solicite datos a nuestra plataforma API, Vonage te envía los datos a través de una solicitud web a tu aplicación. El webhook de Verify API recibe actualizaciones de estado de tus solicitudes y será el resultado de una llamada anterior a la API: este tipo de webhook también se denomina "devolución de llamada".

Recepción de webhooks

Para que los servidores de Vonage puedan enviar datos a tu aplicación a través de webhooks, debes configurar un servidor web para que reciba las solicitudes HTTP entrantes. También debes especificar la URL de cada webhook en tu servidor web para que los datos puedan enviarse a cada uno de ellos.

Para empezar a utilizar los webhooks de Verify:

  1. Crea una Account de Vonage.
  2. Escribe scripts para gestionar la información enviada o solicitada por Vonage. Tu servidor debe responder con un 200 o 204 Respuesta HTTP, como cualquier cosa que no sea un 2xx Este código hará que los servidores de Vonage vuelvan a intentar realizar la devolución de llamada.
  3. Publica tus scripts implementándolos en un servidor. Para el desarrollo local, prueba Ngrok.
  4. Configura tu punto final de webhook de Verify.
  5. Realizar una acción (como envío de una solicitud de verificación por SMS) que activará ese webhook.

A continuación, la información sobre tu solicitud se envía a tu punto final de webhook.

Configurar las URL de los webhooks de Verify

La API de Verify admite un webhook de estado, que se configura en su servidor configuración de la aplicación en el panel de control del desarrollador:

Webhooks can be configured on the customer dashboard

Esto se utiliza para enviar actualizaciones de estado (por ejemplo, eventos de progreso o finalización) de tus solicitudes de Verify.

Probar los webhooks de forma local

Para comprobar que los webhooks funcionan correctamente en tu aplicación ejecutada localmente, tendrás que crear un túnel seguro entre Vonage y tu aplicación. Puedes hacerlo con una aplicación de túneles seguros como, por ejemplo, Ngrok. Véase Pruebas con Ngrok para más información.

Webhooks firmados

Verify que los webhooks estén firmados de forma predeterminada. Los webhooks firmados permiten a tu aplicación verificar que una solicitud procede de Vonage y que su carga útil no ha sido alterada durante la transmisión. Al recibir una solicitud, el webhook entrante incluirá un token JWT en el encabezado de autorización, firmado con tu secreto de firma.

Puedes encontrar más información sobre cómo descodificar webhooks firmados en aquí.

Tipos de devolución de llamada

Devolución de llamada de eventos

Un webhook de eventos entrantes. Esto mostrará el resultado final de su solicitud utilizando la función status campo:

  • completed - La solicitud se ha completado y se ha verificado correctamente la identidad del usuario.
  • blocked - la solicitud se ha bloqueado debido a las reglas de velocidad, o bien el número facilitado es un número de VoIP.
  • failed - la solicitud ha fallado porque el número indicado no es válido.
  • expired - La solicitud no se completó dentro del plazo establecido.
  • user_rejected - el usuario ha introducido un pin incorrecto.
  • cancelled - el usuario canceló la solicitud antes de completar el proceso de autenticación.
  • action_pending - el usuario no ha realizado ninguna acción para iniciar el procedimiento de autenticación. Por ejemplo check_url Aún no se ha producido el momento en el que se le da al usuario la oportunidad de iniciar la autenticación silenciosa.
{
   "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"
}

Autenticación silenciosa

Como parte de un Autenticación silenciosa solicitud, recibirás un función de retorno de llamada de evento a su webhook - por ejemplo:

{
   "request_id": "c11236f4-00bf-4b89-84ba-88b25df97315",
   "triggered_at": "2020-01-01T14:00:00.000Z",
   "type": "event",
   "channel": "silent_auth",
   "status": "action_pending",
   "mode": "advanced",
   "action": {
      "type": "check",
      "check_url": "https://api.nexmo.com/v2/verify/:request_id/silent-auth/redirect"
   }
}

Resumen Devolución de llamada

Las devoluciones de llamada de resumen contienen una actualización del estado de entrada para una solicitud en particular. Como se puede ver en el siguiente ejemplo, hay dos campos de estado - el primero es el estado de la solicitud global, y los otros muestran el resultado de cada canal utilizado en el flujo de trabajo.

Para la solicitud, hay seis valores de Estado diferentes que puede ver:

  • completed - La solicitud se ha completado y se ha verificado correctamente la identidad del usuario.
  • failed - La solicitud ha fallado porque el número facilitado no era válido o no era una dirección IP móvil.
  • expired - la solicitud no se ha completado en el plazo previsto.
  • user_rejected - el usuario introdujo un pin incorrecto tres veces, lo que puso fin al flujo de trabajo.
  • blocked - la solicitud se ha bloqueado debido a las reglas de velocidad, o bien el número facilitado es un número de VoIP.
  • cancelled - el usuario canceló la solicitud antes de completar el proceso de autenticación.

En el flujo de trabajo, hay siete valores de Estado diferentes que puede ver al utilizar la API:

  • unused - el canal no se utilizó ya que la solicitud fue convertida por un canal anterior en el flujo de trabajo.
  • completed - Se utilizó el canal y la verificación se llevó a cabo con éxito.
  • failed - cualquier canal definido en el flujo de trabajo ha fallado porque el número facilitado no era válido o no era una dirección IP móvil, o porque el país en el que se encontraba el usuario no está cubierto por Verify.
  • expired - cualquier canal definido en el flujo de trabajo ha caducado, ya que no se introdujo la contraseña de un solo uso (OTP) dentro del plazo establecido.
  • blocked - El canal SMS/Voz ha sido bloqueado debido a las normas de velocidad.
  • user_rejected - el usuario introdujo un pin incorrecto tres veces, lo que puso fin al flujo de trabajo para el canal utilizado.
  • cancelled- El proceso de autenticación de un canal concreto, definido en el flujo de trabajo, se canceló mientras aún estaba en curso.

Este ejemplo muestra una actualización de una solicitud de verificación completada. En primer lugar, se intentó la autenticación silenciosa, pero se canceló antes de completarse. A continuación, se intentó la autenticación por SMS, pero caducó. Posteriormente, se utilizó WhatsApp y se verificó al usuario con éxito. Dado que no se intentó el canal de voz, el estado aparece como 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": "silent_auth",
         "initiated_at": "2020-01-01T14:00:00.000Z",
         "status": "cancelled",
         "mode": "advanced"
      },
      {
         "channel": "sms",
         "initiated_at": "2020-01-01T14:05:00.000Z",
         "status": "expired"
      },
      {
         "channel": "whatsapp",
         "initiated_at": "2020-01-01T14:10:00.000Z",
         "status": "completed"
      },
      {
         "channel": "voice",
         "initiated_at": "2020-01-01T14:15:00.000Z",
         "status": "unused"
      }
   ],
   "client_ref": "my-personal-ref"
}

El mode indica qué método de autenticación silenciosa se utilizó para el silent_auth paso del flujo de trabajo. Los valores posibles son standard (Autenticación silenciosa) y advanced (Autenticación silenciosa avanzada).

Para completar la solicitud de autenticación silenciosa, tendrás que leer el check_url y enviárselo al cliente para que se autentique.