Verificação de webhooks

Você pode configurar o webhooks que você usa para que a Video API seja protegida 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 JWT no cabeçalho da autorização, que é assinado com sua chave secreta de assinatura.

Callbacks disponíveis da API

• Monitoramento de sessões — Os callbacks do webhook de monitoramento de sessão serão enviados para a URL quando for detectado um evento de sessão.

• Monitoramento do arquivamento — Serão enviadas notificações de arquivamento para informar sobre o andamento das gravações arquivadas e dos arquivos resultantes

• Monitoramento de transmissões — Os eventos de callback de Broadcast serão enviados quando um evento de Broadcast for detectado (por exemplo, quando um Broadcast for criado, atualizado ou excluído).

• Conheça o monitoramento do Composer — Os eventos de callback do Experience Composer serão enviados quando o status do Experience Composer for alterado.

• Monitoramento de legendas em tempo real — Os eventos de retorno de chamada das legendas em tempo real são enviados quando as legendas em tempo real começam, param ou apresentam falha.

• Monitoramento de chamadas SIP — Uma solicitação HTTP será enviada para a URL quando for detectado um evento de chamada SIP

Configurando callbacks seguros

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

2. No menu à esquerda, selecione Applications.

3. Para projetos existentes, clique nos três pontos e selecione o Editar opção e role a página para baixo até a seção de recursos.

4. Para novos projetos, a seção de recursos é exibida após clicar em Criar um novo aplicativo.

5. Ative o botão para habilitar a opção de vídeo.

6. Aparecerá um conjunto de campos de entrada, cada um oferecendo callbacks para diferentes partes da API. Insira uma URL válida nos campos de callback selecionados. Somente então um segredo de assinatura O botão ficará ativo. Clique nele para ativar os callbacks.

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 Salvar alterações 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.).

Você pode ativar quantos callbacks quiser.

As atualizações nas URLs e nos segredos podem levar até 30 minutos para que a configuração seja aplicada 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.

Exemplos de código

const express = require('express');
const jwt = require('@vonage/jwt');
const app = express();

app.use(express.json());

// replace VIDEO_SIGNATURE_SECRET with the secret value set at the Dashboard
const VIDEO_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const payload = request.body;
    const token = request.headers.authorization.split(" ")[1];

    const verified = jwt.verifySignature(token, VIDEO_SIGNATURE_SECRET)
    if (!verified) {
      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'));

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

app.use(express.json());

// replace VIDEO_SIGNATURE_SECRET with the secret value set at the Dashboard
const VIDEO_SIGNATURE_SECRET = process.env.SIGNATURE_SECRET;

app.post('/video/webhook', express.raw({ type: 'application/json' }), (request, response) => {
  try {
    const payload = request.body;
    const token = request.headers.authorization.split(" ")[1];

    const decoded = jwt.verify(
      token,
      VIDEO_SIGNATURE_SECRET,
      { algorithms: ['HS256'] },
      );
    if (!decoded) {
      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. Mais informações podem ser encontradas aqui.

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

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.

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

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 a ser realizadas.