Verify a chamada

O vcr O objeto no SDK permite que você verifique se um callback recebido pelo seu aplicativo é proveniente da plataforma Vonage Cloud Runtime. Todas as solicitações feitas à sua instância a partir da plataforma Vonage Cloud Runtime incluirão um JWT assinado com a chave privada do seu aplicativo Vonage no Authorization cabeçalho.

Importante: Se o seu aplicativo utiliza os provedores de assinatura do VCR (Mensagens, Voz ou Conversação), os webhooks são encaminhados por meio do roteador de callback do VCR. Nesse caso, o Authorization O cabeçalho autentica apenas o próprio roteador de retorno de chamada — ele faz isso não garantir que o evento original tenha vindo da Vonage ou que a carga útil não tenha sido adulterada durante o trânsito. Para verificar completamente a origem desses webhooks, você também deve validar o X-Vonage-Webhook-Auth-Token cabeçalho, conforme descrito a seguir.

Você pode verificar se isso se aplica ao seu aplicativo conferindo a URL do seu webhook. Se ela começar com qualquer uma das seguintes URLs, seu aplicativo está recebendo webhooks por meio do roteador de callback do VCR e você deve seguir as etapas adicionais de verificação descritas neste guia:

  • https://callback-router.euw1.runtime.vonage.cloud/
  • https://callback-router.use1.runtime.vonage.cloud/
  • https://callback-router.apse1.runtime.vonage.cloud/
  • https://callback-router.apse2.runtime.vonage.cloud/

Se você configurou manualmente as URLs dos seus webhooks para apontar diretamente para a URL da sua instância pública, isso não se aplica.

Recupere seu segredo do Webhook da Vonage

Para validar o X-Vonage-Webhook-Auth-Token No cabeçalho, você precisará do seu segredo do webhook da Vonage.

  1. Faça login no Painel da API da Vonage.
  2. Acesse as configurações do seu aplicativo.
  3. Localize o Segredo do Webhook (também conhecido como “Segredo de Assinatura”) nas configurações de segurança.
  4. Armazene esse valor de forma segura nas variáveis de ambiente do seu aplicativo (por exemplo, como VONAGE_WEBHOOK_SECRET). Não o insira diretamente no seu código-fonte.

Verify the JWT of the Callback Router (Authorization cabeçalho)

Uso vcr.verifyAuth() para confirmar que a solicitação foi enviada pelo roteador de retorno de chamada do VCR. Essa etapa continua válida e deve ser mantida como uma primeira camada de verificação.

Assinatura do método:

vcr.verifyAuth(token: string)

Uso verifyAuth em uma função de middleware. Ela gerará um erro se o token não for válido.

// Express Example
const authMiddleware = (req, res, next) => {
    const token = req.headers['authorization'];
    if (!token) {
        return res.status(401).json({ error: 'Missing Authorization header' });
    }

    try {
        vcr.verifyAuth(token);
        next();
    } catch (error) {
        return res.status(401).json({ error: error.message });
    }
};

Verifique o token de origem da Vonage (X-Vonage-Webhook-Auth-Token cabeçalho)

Para aplicativos que utilizam o roteador de callbacks do VCR, é necessário validar adicionalmente o X-Vonage-Webhook-Auth-Token cabeçalho. Esse token é assinado pela Vonage e permite que você confirme criptograficamente que o evento realmente se originou da Vonage e não sofreu alterações.

const jwt = require('jsonwebtoken');

const verifyVonageOrigin = (req, res, next) => {
    const vonageToken = req.headers['x-vonage-webhook-auth-token'];

    if (!vonageToken) {
        return res.status(401).json({ error: 'Missing X-Vonage-Webhook-Auth-Token header' });
    }
    try {
        // Verify the token using your Vonage Webhook Secret
        jwt.verify(vonageToken, process.env.VONAGE_WEBHOOK_SECRET, { algorithms: ['HS256'] });
        next();
    } catch (error) {
        return res.status(401).json({ error: 'Invalid Vonage origin token: ' + error.message });
    }
};

Não está usando o roteador de retorno de chamada VCR?

Se o seu aplicativo receber webhooks diretamente (ou seja, se a URL do seu webhook não começar com https://callback-router.euw1.runtime.vonage.cloud/), o Authorization O cabeçalho contém o JWT original assinado pela Vonage — emitido pela plataforma da Vonage, e não pela VCR.

Nesse caso, Você deve validar o token usando o seu segredo do Webhook da Vonage.