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 permitir que los servidores de Vonage envíen datos a tu aplicación a través de webhooks, debes configurar un servidor web para recibir las solicitudes HTTP entrantes. También debes especificar la URL de cada webhook en tu servidor web para que se puedan enviar datos a cada uno.

Para empezar a utilizar los webhooks de Verify:

  1. Crea una Account de Vonage.
  2. Escribe scripts para manejar 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 hará que los servidores de Vonage vuelvan a intentar la devolución de llamada.
  3. Publica tus scripts desplegándolos en un servidor. Para el desarrollo local, pruebe Ngrok.
  4. Configure su punto final Verify webhook.
  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 su solicitud se envía a su punto final 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

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

Probar los webhooks localmente

Para probar el correcto funcionamiento de los webhooks en tu aplicación que se ejecuta localmente, necesitarás crear un túnel seguro entre Vonage y tu aplicación. Puedes hacerlo con una aplicación de túnel seguro como Ngrok. Véase Pruebas con Ngrok para más información.

Webhooks firmados

Los webhooks de Verify están firmados de manera predeterminada. Los webhooks firmados permiten que tu aplicación verifique que una solicitud proviene de Vonage y que su carga útil no ha sido alterada durante el tránsito. Al recibir una solicitud, el webhook entrante incluirá un token JWT en el encabezado de autorización que está firmado con tu firma secreta.

Encontrará más información sobre la descodificación de 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 el usuario se ha verificado correctamente.
  • blocked - la solicitud fue bloqueada debido a las normas de velocidad, o el número proporcionado es un VOIP.
  • failed - la solicitud ha fallado porque el número indicado no es válido.
  • expired - la solicitud no se ha completado en el 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 que se le da al usuario para iniciar la autenticación silenciosa aún no se ha producido.
{
   "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á un evento callback 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",
   "action": [
      {
         "type": "check",
         "check_url": "https://eu.api.silent.auth/phone_check/v0.1/checks/:request_id/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 el usuario se ha verificado correctamente.
  • failed - la solicitud falló porque el número indicado no era un número válido o no era una 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 fue bloqueada debido a las normas de velocidad, o el número proporcionado es un 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 dio lugar a una verificación satisfactoria.
  • failed - cualquier canal definido en el flujo de trabajo falló porque el número dado no era un número válido o no era una IP móvil, o 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 al no haberse introducido la 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 específico definido en el flujo de trabajo se canceló mientras aún estaba en curso.

Este ejemplo muestra una actualización para una solicitud de verificación completada. El primer canal intentó utilizar SMS, pero la solicitud caducó. A continuación, se utilizó WhatsApp y el usuario se verificó correctamente. Como no se intentó utilizar el canal de voz, el estado es el siguiente 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"
}

Para completar la solicitud de autenticación silenciosa, tendrá que leer el archivo check_url y pasarlo al cliente para autenticarse.