Verify webhooks da API

Introdução

Webhooks são uma extensão de uma API — em vez de seu código solicitar dados da nossa plataforma de API, a Vonage envia os dados a você por meio de uma solicitação da web para o seu aplicativo. O webhook da API Verify recebe atualizações de status sobre suas solicitações e será o resultado de uma chamada de API anterior — esse tipo de webhook também é chamado de “callback”.

Recebimento de webhooks

Para permitir que os servidores da Vonage enviem dados para o seu aplicativo por meio de webhooks, é necessário configurar um servidor web para receber as solicitações HTTP recebidas. Também é necessário especificar a URL de cada webhook no seu servidor web para que os dados possam ser enviados a cada um deles.

Para começar a usar os webhooks do Verify:

1. Crie um account na Vonage.
2. Escreva scripts para processar as informações enviadas ou solicitadas pela Vonage. Seu servidor deve responder com um 200 ou 204 Resposta HTTP, desde que não seja um 2xx Esse código fará com que os servidores da Vonage tentem novamente a entrega da chamada de retorno.
3. Publique seus scripts fazendo a implantação em um servidor. Para desenvolvimento local, experimente Ngrok.
4. Configure seu endpoint do webhook do Verify.
5. Realize uma ação (como, por exemplo, enviar uma solicitação de verificação por SMS) que acionará esse webhook.

As informações sobre sua solicitação são então enviadas para o seu endpoint de webhook.

Configure as URLs dos webhooks do Verify

A API Verify oferece suporte a um webhook de status, que é configurado em seu configurações do aplicativo no painel do desenvolvedor:

Isso é usado para enviar atualizações de status (por exemplo, eventos de progresso ou conclusão) para suas solicitações de Verify.

Testando webhooks localmente

Para testar o funcionamento correto dos webhooks em seu aplicativo executado localmente, você precisará criar um túnel seguro entre a Vonage e seu aplicativo. Você pode fazer isso usando um aplicativo de túnel seguro, como Ngrok. Veja Testes com o Ngrok para mais informações.

Webhooks assinados

Verify se os webhooks estão assinados por padrão. Os webhooks assinados permitem que seu aplicativo verifique se uma solicitação está vindo da Vonage e se sua carga útil não foi adulterada durante o trânsito. Ao receber uma solicitação, o webhook recebido incluirá um token JWT no cabeçalho de autorização, assinado com seu segredo de assinatura.

Mais informações sobre a decodificação de webhooks assinados podem ser encontradas aqui.

Tipos de callback

Retorno de chamada de eventos

Um webhook de eventos de entrada. Ele exibirá o resultado final da sua solicitação usando o status campo:

• completed - a solicitação foi concluída e o usuário foi verificado com sucesso.
• blocked - a solicitação foi bloqueada devido às regras de velocidade, ou o número fornecido é um número de VOIP.
• failed - A solicitação falhou, pois o número fornecido não era válido.
• expired - a solicitação não foi concluída dentro do prazo estabelecido.
• user_rejected - o usuário digitou um PIN incorreto.
• cancelled - o usuário cancelou a solicitação antes de concluir o processo de autenticação.
• action_pending - o usuário não realizou nenhuma ação para iniciar o procedimento de autenticação. Por exemplo, o check_url Ainda não ocorreu o momento em que o usuário tem a oportunidade de iniciar a autenticação 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"
}

Autenticação silenciosa

Como parte de um Autenticação silenciosa solicitação, você receberá um chamada de retorno de evento para o seu webhook — por exemplo:

{
   "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"
   }
}

Resumo da chamada de retorno

Os callbacks de resumo contêm uma atualização do status de entrada para uma solicitação específica. Como você pode ver no exemplo abaixo, há dois campos “Status” — o primeiro é o status da solicitação como um todo, e os demais mostram o resultado de cada canal utilizado no fluxo de trabalho.

Para a solicitação, há seis valores diferentes de Status que você pode encontrar:

• completed - a solicitação foi concluída e o usuário foi verificado com sucesso.
• failed - a solicitação falhou porque o número fornecido não era válido ou não era um endereço IP móvel.
• expired - a solicitação não foi concluída dentro do prazo estabelecido.
• user_rejected - o usuário digitou um PIN incorreto três vezes, o que interrompeu o fluxo de trabalho.
• blocked - a solicitação foi bloqueada devido às regras de velocidade, ou o número fornecido é um número de VOIP.
• cancelled - o usuário cancelou a solicitação antes de concluir o processo de autenticação.

No fluxo de trabalho, há sete valores de status diferentes que você pode encontrar ao usar a API:

• unused - o canal não foi utilizado, pois a solicitação foi convertida por um canal anterior no fluxo de trabalho.
• completed - o canal foi utilizado e resultou em uma verificação bem-sucedida.
• failed - algum canal definido no fluxo de trabalho apresentou falha porque o número fornecido não era válido ou não era um endereço IP móvel, ou porque o país em que o usuário estava localizado não é coberto pelo Verify.
• expired - qualquer canal definido no fluxo de trabalho expirou, pois a senha de uso único (OTP) não foi inserida dentro do prazo estipulado.
• blocked - O canal SMS/voz foi bloqueado devido às regras de velocidade.
• user_rejected - o usuário digitou um PIN incorreto três vezes, o que interrompeu o fluxo de trabalho do canal utilizado.
• cancelled- o processo de autenticação de um canal específico, definido no fluxo de trabalho, foi cancelado enquanto ainda estava em andamento.

Este exemplo mostra uma atualização referente a uma solicitação de verificação concluída. Primeiro, foi tentada a autenticação silenciosa, mas ela foi cancelada antes de ser concluída. Em seguida, foi tentada a autenticação por SMS, mas o prazo expirou. Depois, utilizou-se o WhatsApp e o usuário foi verificado com sucesso. Como o canal de voz não foi tentado, o status 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"
}

Para concluir a solicitação de autenticação silenciosa, você precisará ler o check_url e enviá-lo ao cliente para autenticação.