Callbacks seguros

Você pode configurar os webhooks que utiliza para a Video API de forma que sejam protegidos por callbacks assinados.

O recurso de callbacks seguros oferece um método para que seu aplicativo verifique se uma solicitação de callback de webhook está vindo da Vonage e se sua carga útil não foi adulterada durante o trânsito. Ao receber uma solicitação, o webhook de callback recebido incluirá um token JWT no cabeçalho de autorização, que é assinado com seu segredo de assinatura.

Os seguintes callbacks da API podem ser protegidos por meio de callbacks assinados e configurados com seu próprio segredo de assinatura:

  • Monitoramento de sessões — Monitore a atividade da sessão registrando uma URL de retorno de chamada. As chamadas de retorno do webhook de monitoramento de sessão serão enviadas para essa URL quando for detectado um evento de sessão.

  • Monitoramento do arquivamento — Monitore o status do arquivamento registrando uma URL de retorno de chamada. Serão enviadas notificações de retorno de chamada para informar sobre o status das gravações arquivadas e dos arquivos resultantes

  • Monitoramento de chamadas SIP — Monitore a atividade de chamadas SIP registrando uma URL de retorno de chamada. Uma solicitação HTTP será enviada para essa URL quando for detectado um evento de chamada SIP

  • Monitoramento de transmissões — Monitore a atividade do Broadcast registrando uma URL de retorno de chamada. Os eventos de retorno de chamada do Broadcast serão enviados quando um evento do Broadcast for detectado (por exemplo, quando um Broadcast for criado, atualizado ou excluído).

  • Conheça o monitoramento do Composer — Monitore a atividade do Experience Composer registrando uma URL de retorno de chamada. Os eventos de retorno de chamada do Experience Composer serão enviados quando o status do Experience Composer for alterado.

  • Monitoramento de legendas em tempo real — Monitore a atividade do Live Captions registrando uma URL de retorno de chamada. Os eventos de retorno de chamada do Live Captions são enviados quando as legendas em tempo real começam, param ou apresentam falha.

Configurando callbacks seguros

As instruções a seguir podem ser utilizadas para habilitar o Monitoramento de Sessão como um callback seguro. Você também pode seguir essas instruções de maneira semelhante para outros callbacks (para monitoramento de arquivos, monitoramento de chamadas SIP e monitoramento do Experience Composer).

  1. Faça login na sua Account da Video API da Vonage.

  2. No menu à esquerda, selecione a Account desejada.

  3. No menu à esquerda, selecione o Projeto para o qual você deseja registrar um callback seguro.

  4. Encontrar Monitoramento de sessões (ou a seção apropriada) e clique em Configurar.

  5. A interface do usuário inclui opções para configurar a URL de retorno de chamada e (opcionalmente) um segredo de assinatura.

  6. Sempre que o campo “segredo de assinatura” for ativado, o sistema fornecerá um segredo de assinatura gerado aleatoriamente. Esse valor de segredo de assinatura preenchido automaticamente pode ser usado ou substituído por um valor escolhido pelo usuário. Ao receber uma chamada de retorno, o webhook recebido será assinado com o segredo de assinatura configurado nesse campo. Clique em Enviar para configurar esse segredo para que seja usado em callbacks seguros. (Observação: o segredo de assinatura deve ser uma sequência de caracteres, com comprimento mínimo de 1 caractere e máximo de 50 caracteres.)

  7. O sistema informará que os callbacks seguros foram configurados com a URL e o segredo de assinatura. Observe que as atualizações podem levar até 30 minutos para aplicar a configuração na plataforma.

Validação de callbacks seguros

A validação de callbacks seguros 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

A validação de callbacks seguros consiste em duas etapas:

  • Verificação da solicitação

  • Verificação da carga útil (opcional)

Verificação da solicitação

As respostas incluirão um JWT no cabeçalho Authorization. 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 à chave de API (api_key) incluída nas reivindicações do JWT. Você pode identificar seu segredo de assinatura por meio do Portal do account da Video API da Vonage.

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 a carga útil da solicitação não foi adulterada, comparando um hash SHA-256 da carga útil com o campo `payload_hash` encontrado nas reivindicações do JWT. Se eles não corresponderem, isso significa que a carga útil foi adulterada durante o trânsito. Você só precisa verificar a carga se estiver usando HTTP em vez de HTTPS, pois o Transport Layer Security (TLS) impede Ataques MITM.

Exemplo de código

O exemplo a seguir do Express mostra como Verify 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.

const express = require('express');
const jwt = require('jsonwebtoken');
const sha256 = require('js-sha256');
const app = express();


app.use(express.json());

const VONAGE_API_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const userAgent = request.headers['user-agent'];
    if (userAgent !== 'Vonage/Callback/v1.0') {
      console.log('Bad token detected');
      return response.status(401).send();
    } else {
      const payload = request.body;
      let token = request.headers.authorization.split(" ")[1];
      // replace VIDEO_CALLBACK_SECRET with the secret value set at the Dashboard
      var decoded = jwt.verify(
        token,
        VONAGE_API_SIGNATURE_SECRET,
        { algorithms: ['HS256'] },
        );
      if (sha256(JSON.stringify(payload)) != decoded['payload_hash']) {
        console.log('tampering detected');
        response.status(401).send();
      }
    }
    console.log('Success');
    return response.status(204).send();
  } catch (err) {
    if (err instanceof JsonWebTokenError  || err instanceof TokenExpiredError){
      console.log('Token Error', err.message);
    } else {
      console.error(err);
    }
    return response.status(401).send();
  }
});

app.listen(4242, () => console.log('Running on port 4242'));

Limitações/Considerações conhecidas

A seção a seguir aborda as limitações e considerações a serem levadas em conta antes de ativar esse recurso.

Endereço IP de retorno de chamada

Uma vez habilitado para retornos de chamada seguros, o intervalo de endereços IP utilizado pelo serviço de retorno de chamada da Vonage será diferente do intervalo usado nos retornos de chamada anteriores da Video API. Por favor, permita o intervalo a seguir para possibilitar uma comunicação sem interrupções com os retornos de chamada seguros da Vonage: 216.147.0.0/18.

TLS mútuo (mTLS)

O mTLS é compatível com o fluxo de callbacks seguros. (Anteriormente, não era)

Alterações na política de repetição de chamadas de retorno e de recuo

Uma vez ativada a função de callbacks seguros, haverá uma mudança no comportamento da política de repetição de tentativas e de intervalo de espera para callbacks.

Observe que as tentativas de repetição são realizadas apenas em caso de problemas de conectividade (e não para outros erros).

O que acontecerá se os eventos de callback do meu aplicativo deixarem de funcionar?

  • Comportamento anterior: A Vonage tentará novamente 4 vezes para cada evento que não conseguirmos entregar ao servidor de aplicativos.

    Apenas para monitoramento de sessão — Se a plataforma detectar 50 falhas de entrega em um intervalo de 30 minutos, o encaminhamento de eventos será desativado para os callbacks de monitoramento de sessão. Um e-mail de notificação foi enviado ao cliente para informar que os callbacks foram desativados. Para reativar o encaminhamento de eventos, a URL de callback do monitoramento de sessão precisou ser configurada novamente por meio do Portal da Conta da Video API do Vonage.

  • Novo comportamento: Após 24 horas, a lógica de repetição de tentativas de callback individual será interrompida e o evento de callback individual não será mais enviado. No entanto, as tentativas de callback para novos eventos continuarão sendo realizadas.

Importante: No caso de falhas excessivas na entrega, o novo serviço não desativará mais o encaminhamento de eventos, uma vez que será utilizado o mecanismo de repetição de tentativas e recuo. Portanto, não haverá mais nenhuma notificação por e-mail indicando que os callbacks foram desativados e precisam ser reativados, pois o novo serviço não suspenderá nem desativará os callbacks de forma alguma.