Webhooks

Os webhooks são uma extensão de uma API, mas, em vez de seu código solicitar dados à nossa plataforma de API, a Vonage envia os dados diretamente para você. Os dados chegam por meio de uma solicitação da web ao seu aplicativo. Um webhook pode ser o resultado de uma chamada de API anterior (esse tipo de webhook também é chamado de “callback”), como uma solicitação assíncrona à Number Insight API. Os webhooks também são usados para notificar seu aplicativo sobre eventos, como uma chamada ou mensagem recebida.

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

Fluxo de trabalho de webhooks

Com os webhooks, é importante que a URL para a qual os webhooks serão enviados esteja configurada. Quando há dados disponíveis, a Vonage envia o webhook para o seu aplicativo na forma de uma solicitação HTTP. Seu aplicativo deve responder com um código de sucesso HTTP para indicar que recebeu os dados com sucesso.

O processo é mais ou menos assim:

Os webhooks oferecem um mecanismo prático para que a Vonage envie informações ao seu aplicativo sobre eventos como uma chamada ou mensagem recebida, ou uma alteração no status da chamada. Eles também podem ser usados para enviar informações complementares, como um comprovante de entrega, que pode ficar disponível algum tempo após a solicitação à qual se refere.

Quais APIs oferecem suporte a webhooks?

As informações resultantes de solicitações às APIs compatíveis da Vonage são enviadas por meio de uma solicitação HTTP para o seu endpoint de webhook em um servidor HTTP. Para configurar o seu endpoint de webhook, acesse o Painel do Vonage.

A Vonage envia e recebe as seguintes informações por meio de webhooks:

Configurando pontos de extremidade de webhooks

Os webhooks são usados para enviar mensagens recebidas e confirmaciones de entrega.

Mensagens recebidas

Para configurar o webhook usado para mensagens recebidas, acesse o Seus Numbers seção do Painel da Vonage. Clique em “editar” no número virtual e defina o URL de retorno de chamada.

Você também pode usar o CLI da Vonage para definir o ponto de conexão de mensagens recebidas para um número específico.

Comprovantes de entrega

Veja o Comprovantes de entrega guia na documentação do SMS.

A Number Insight API Advanced permite que você receba os resultados de uma consulta de número de forma síncrona ou assíncrona.

Defina o callback parâmetro com a URL de um webhook para receber a consulta de forma assíncrona.

Veja Number Insight Asíncrono Avançado para mais detalhes.

Para solicitações da Voice API, os webhooks podem ser configurados no nível do aplicativo, ao criar uma chamada ou nas ações de um NCCO.

Webhooks no nível do aplicativo

The Vonage numbers linked to Vonage applications will use the answer_url para recuperar um NCCO, e o event_url para enviar informações sobre o status da chamada para você. O fallback_answer_url pode ser configurado opcionalmente. Isso é usado quando answer_url está offline ou retornando um código de erro HTTP. Também é usado quando se espera que um evento entregue um NCCO em event_url, mas event_url está offline ou retornando um código de status HTTP.

Você pode configurá-los usando o API do aplicativo, no painel de controle ou usando o CLI da Vonage ferramenta.

Webhooks no nível do número

Você pode configurar um webhook de status para cada número que adquirir. Ele será usado para enviar eventos a você relativos a cada número.

Essas configurações podem ser definidas na seção “Numbers” do Painel de controle, por meio do CLI da Vonage ou pelo Atualizar um número Chamada de API (mais especificamente, a voiceStatusCallback propriedade).

Sobre como fazer uma chamada de saída

Quando fazer uma nova chamada de saída, é preciso definir o answer_url na chamada para uma URL que contenha um NCCO. Os servidores da Vonage irão recuperar o NCCO desse ponto de extremidade e seguirão suas instruções para processar a chamada de saída.

Conteúdo da resposta da URL

A carga útil para o answer_url é:

Parâmetro	Descrição
to	O número que está sendo chamado
from	O número de quem está ligando
conversation_uuid	O UUID do conversa
uuid	O UUID do perna

URL de exemplo:

Copiar

/webhooks/answer?to=447700900000&from=447700900001&conversation_uuid=CON-aaaaaaaa-bbbb-cccc-dddd-0123456789ab&uuid=aaaaaaaa-bbbb-cccc-dddd-0123456789cd

Por dentro de um NCCO

Dentro de um NCCO, os seguintes tipos de ação aceitam uma URL de webhook para ser utilizada quando essa ação for executada:

• record.eventUrl - definir o endpoint do webhook que recebe informações sobre a gravação de uma chamada ou conversa
• conversation.eventUrl - defina a URL do endpoint do webhook que a Vonage aciona de forma assíncrona quando o estado de uma conversa muda para essa ação da conversa
• connect.eventUrl - defina a URL do endpoint do webhook que a Vonage aciona de forma assíncrona quando uma conversa muda de estado para esta ação de conexão
• input.eventUrl - defina a URL do endpoint do webhook para o qual a Vonage envia os dígitos digitados pelo destinatário da chamada
• stream.streamUrl - definir uma matriz de URLs que apontem para os endpoints de webhook que hospedam o arquivo de áudio a ser transmitido para a chamada ou conversa

Tempos limite dos webhooks

Se a resposta, o evento ou a URL alternativa ficarem inacessíveis por um determinado período de tempo, ou se o tempo de resposta exceder um determinado limite, a Vonage tentará a solicitação novamente uma vez. Os tempos limite padrão da plataforma para conexão e leitura são os seguintes:

Tipo de webhook	Tempo limite de conexão	Tempo limite do soquete
Resposta	1 segundo	5 segundos
Evento	1 segundo	10 segundos
Solução alternativa	1 segundo	5 segundos

Essas configurações padrão podem ser substituídas por meio de um API do aplicativo ligue ou no Painel de controle selecionando o aplicativo e, em seguida, clicando no Editar botão e rolando até a seção Recursos / Voz:

Mais informações sobre esses tempos limite podem ser encontradas no tempos limite de webhooks seção da API do aplicativo visão geral documentação.

Um Applications pode receber eventos RTC por meio do Webhook do RTC.

Você define a URL do webhook do evento RTC quando criar o aplicativo usando o idioma de sua preferência.

Mais informações sobre como criar uma aplicação com recursos de RTC também podem ser encontradas no Documentação da API do aplicativo.

O Verify envia callbacks de eventos e resumos para atualizações sobre suas solicitações de verificação. Se você escolher a Autenticação Silenciosa ou o WhatsApp Codeless como um de seus canais de autenticação, será necessário receber esses callbacks para concluir a solicitação com sucesso.

A URL para a qual os callbacks serão enviados pode ser configurada no seu configurações do aplicativo no painel do desenvolvedor. Consulte o Referência da API por exemplo, callbacks.

Existem dois webhooks compatíveis com as APIs de Mensagens e Dispatch API: o webhook de Status da Mensagem e o webhook de Mensagem Recebida. O status da mensagem é recebido no webhook de Status da Mensagem, enquanto a própria mensagem é recebida no webhook de Mensagem Recebida. A configuração desses webhooks é descrita em detalhes no tópico Configurando webhooks para as APIs do Messages e da Dispatch API.

Recebimento de webhooks

Para interagir com os webhooks da Vonage:

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 código de status de sucesso (qualquer código de status entre 200 OK e 205 Reset Content) às mensagens recebidas da Vonage. Qualquer coisa diferente de 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. Configurar um endpoint de webhook na API que você deseja usar.
5. Realize uma ação (como enviar um SMS) que acione esse webhook.

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

Decodificação de webhooks assinados

A assinatura de webhooks é ativada por padrão para as APIs de Mensagens, Dispatch, Verify e Voice API. Elas oferecem um método para 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.

NOTA: Para Applications do Voice criadas anteriormente, a opção “Webhooks assinados” está desativada por padrão. Para ativá-la manualmente, acesse as configurações do aplicativo no Painel, clique no link “Mostrar recursos avançados” na seção “Recursos do Voice” e, em seguida, ative a Use webhooks assinados verificar:

Você também pode desativar essa opção para novos aplicativos marcando esta caixa de seleção (não recomendado; use apenas em casos excepcionais).

A validação de webhooks assinados oferece diversos benefícios de segurança, incluindo:

• A capacidade de verificar se uma solicitação tem origem na Vonage
• Garantir que a mensagem não tenha sido adulterada durante o trânsito
• Proteção contra interceptação e reprodução posterior

Validação de webhooks assinados

A validação de webhooks assinados consiste em duas etapas:

1. Verificação da solicitação
2. Verificação da carga útil (opcional)

Verificação da solicitação

Os webhooks incluirão um JWT no Authorization cabeçalho. Use a chave de API incluída nas reivindicações do JWT para identificar qual dos seus segredos de assinatura foi usado para assinar a solicitação. O segredo usado para assinar a solicitação corresponde ao segredo de assinatura associado ao api_key incluídos nos campos do JWT. Você pode identificar seu segredo de assinatura no Painel de controle. Recomenda-se que os segredos de assinatura tenham pelo menos 32 bits para garantir sua segurança.

Verify se a carga útil não sofreu adulteração durante o transporte

Depois de verificar a autenticidade da solicitação, você pode, opcionalmente, verificar se o conteúdo da solicitação não foi adulterado, comparando o hash SHA-256 desse conteúdo com o payload_hash campo encontrado nas reivindicações do JWT. Se não corresponderem, isso significa que a carga útil foi adulterada durante o trânsito. Você só precisa verificar a carga útil se estiver usando HTTP em vez de HTTPS, já que o Transport Layer Security (TLS) impede Ataques MITM.

O exemplo de código abaixo mostra como verificar a assinatura de um webhook. Recomenda-se o uso do protocolo HTTPS, pois ele garante que a solicitação e a resposta sejam criptografadas tanto no lado do cliente quanto no lado do servidor.

npm install @vonage/jwt express

const app = require('express')();
const bodyParser = require('body-parser');

app.use(bodyParser.json());
app.use(bodyParser.urlencoded({
  extended: true,
}));

app
  .route('/webhooks/inbound-message')
  .post(handleInboundMessage);

const handleInboundMessage = (request, response) => {
  const token = request.headers.authorization.split(' ')[1];
  if (verifySignature(token, VONAGE_API_SIGNATURE_SECRET)) {
    console.log('Valid signature');
  } else {
    console.log('Invalid signature');
  }

  response.send(200);
};

app.listen(process.env.PORT || 3000);

composer require vonage/client

require_once __DIR__ . '../../config.php';
require_once __DIR__ . '../../vendor/autoload.php';

$signature = new Vonage\Client\Credentials\SignatureSecret(VONAGE_API_KEY, VONAGE_SIGNATURE_SECRET, 'sha256');
$client = new Vonage\Client($signature);

$message = new Vonage\SMS\Message\SMS(
    TO_NUMBER,
    FROM_NUMBER,
    'This is a signed text'
);

$client->sms()->send($message);

// Incoming Request
$signature = new Vonage\Client\Signature($_GET, VONAGE_SIGNATURE_SECRET, 'sha256');
$isValid = $signature->check($_GET['sig']);

pip install vonage python-dotenv fastapi[standard]

import os
from os.path import dirname, join

from dotenv import load_dotenv

# Load the environment
envpath = join(dirname(__file__), '../.env')
load_dotenv(envpath)


VONAGE_SIGNATURE_SECRET = os.getenv('VONAGE_SIGNATURE_SECRET')

from fastapi import FastAPI, Request
from vonage_jwt.verify_jwt import verify_signature

app = FastAPI()


@app.get('/inbound')
async def verify_signed_webhook(request: Request):
    # Need to get the JWT after "Bearer " in the authorization header
    auth_header = request.headers["authorization"].split()
    token = auth_header[1].strip()

    if verify_signature(token, VONAGE_SIGNATURE_SECRET):
        print('Valid signature')
    else:
        print('Invalid signature')

Exemplo de JWT assinado

// header
{
  "alg": "HS256",
  "typ": "JWT",
}
// payload
{
  "iat": 1587494962,
  "jti": "c5ba8f24-1a14-4c10-bfdf-3fbe8ce511b5",
  "iss": "Vonage",
  "payload_hash" : "d6c0e74b5857df20e3b7e51b30c0c2a40ec73a77879b6f074ddc7a2317dd031b",
  "api_key": "a1b2c3d",
  "application_id": "aaaaaaaa-bbbb-cccc-dddd-0123456789ab"
}

Cabeçalho JWT assinado

O conteúdo do cabeçalho do JWT assinado é descrito na tabela a seguir:

Carga útil do JWT assinada

O conteúdo da carga útil do JWT assinado é descrito na tabela a seguir, utilizando os valores incluídos no exemplo de JWT assinado apresentado anteriormente:

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. Consulte o Testes com o Ngrok tópico para obter mais informações.

Configurando seu firewall

Se você restringir o tráfego de entrada (incluindo recibos de entrega), será necessário adicionar os endereços IP da Vonage à lista de endereços IP aprovados do seu firewall. Você pode encontrar mais informações sobre como fazer isso em nossa base de conhecimento:

• Intervalos de IP para voz
• Intervalos de IP para SMS
• Mensagens e intervalos de IP de despacho
• Number Insight: Intervalos de IP assíncronos avançados

Dicas para depurar webhooks

Comece aos poucos - Publique o script mais simples possível que você conseguir imaginar para responder ao recebimento do webhook e, talvez, exibir algumas informações de depuração. Isso garante que a URL seja a que você imagina e que você possa ver a saída ou os logs do aplicativo.

Programe de forma defensiva - Verifique se os valores dos dados existem e se contêm o que você esperava antes de prosseguir e utilizá-los. Dependendo da sua configuração, você pode estar sujeito a receber dados inesperados; portanto, tenha isso sempre em mente.

Veja os exemplos - A Vonage fornece exemplos implementados com diversas pilhas de tecnologia, com o objetivo de oferecer suporte ao maior número possível de desenvolvedores. Para ver exemplos de código que utilizam webhooks, consulte o seguinte:

• Receber um SMS
• Gerenciar recibos de entrega
• Receber uma chamada

Você também pode consultar a seção de trechos de código da documentação da API que está usando.

Veja também

• Mais informações sobre os tipos de webhooks e os recursos das Applications podem ser encontradas no Documentação da inscrição.