Devoluciones de llamada seguras

Puedes configurar los webhooks que utilizas para la Video API de modo que estén protegidos mediante callbacks firmados.

La función de callbacks seguros ofrece a tu aplicación un método para verificar que una solicitud de callback de webhook procede de Vonage y que su carga útil no ha sido alterada durante la transmisión. Al recibir una solicitud, el webhook de callback entrante incluirá un token JWT en el encabezado de autorización, firmado con tu secreto de firma.

Las siguientes funciones de devolución de llamada de la API pueden protegerse mediante funciones de devolución de llamada firmadas y configurarse con su propio secreto de firma:

  • Supervisión de sesiones — Supervisa la actividad de la sesión registrando una URL de devolución de llamada. Las devoluciones de llamada del webhook de supervisión de sesiones se enviarán a dicha URL cuando se detecte un evento de sesión.

  • Supervisión del archivo — Supervisa el estado del archivo registrando una URL de devolución de llamada. Se enviarán notificaciones de devolución de llamada del archivo para informar de los eventos relacionados con el estado de las grabaciones archivadas y los archivos resultantes.

  • Supervisión de llamadas SIP — Supervisa la actividad de las llamadas SIP registrando una URL de devolución de llamada. Se enviará una solicitud HTTP a dicha URL cuando se detecte un evento de llamada SIP.

  • Control de emisiones — Supervisa la actividad de Broadcast registrando una URL de devolución de llamada. Se enviarán eventos de devolución de llamada de Broadcast cuando se detecte un evento de Broadcast (por ejemplo, cuando se cree, actualice o elimine un Broadcast).

  • Descubre la supervisión de Composer — Supervisa la actividad de Experience Composer registrando una URL de devolución de llamada. Los eventos de devolución de llamada de Experience Composer se enviarán cuando cambie el estado de Experience Composer.

  • Supervisión de subtítulos en directo — Supervisa la actividad de «Live Captions» registrando una URL de devolución de llamada. Los eventos de devolución de llamada de «Live Captions» se envían cuando los subtítulos en directo se inician, se detienen o fallan.

Configuración de devoluciones de llamada seguras

Las siguientes instrucciones sirven para habilitar la supervisión de sesiones mediante una llamada de retorno segura. También puedes seguir estas instrucciones de forma similar para otras llamadas de retorno (para la supervisión de archivos, la supervisión de llamadas SIP y la supervisión de Experience Composer).

  1. Conéctese a su Account de la Video API de Vonage.

  2. En el menú de la izquierda, selecciona la Account que desees.

  3. En el menú de la izquierda, selecciona el proyecto para el que deseas registrar una llamada de retorno segura.

  4. Buscar Control de la sesión (o la sección correspondiente) y haz clic en Configure.

  5. La interfaz de usuario incluye opciones para configurar la URL de devolución de llamada y (opcionalmente) un secreto de firma.

  6. El sistema proporcionará un secreto de firma generado aleatoriamente cada vez que se active el campo «Secreto de firma». Este valor de secreto de firma preestablecido puede utilizarse tal cual o sustituirse por un valor elegido por el usuario. Al recibir una llamada de retorno, el webhook entrante se firmará con el secreto de firma configurado en dicho campo. Haz clic en Enviar para configurar este secreto de modo que se utilice para las respuestas seguras. (Nota: el secreto de firma debe ser una cadena de caracteres, con una longitud mínima de 1 carácter y una máxima de 50 caracteres.)

  7. El sistema indicará que se han configurado las llamadas de retorno seguras con la URL y el secreto de firma. Ten en cuenta que las actualizaciones pueden tardar hasta 30 minutos en aplicar la configuración en la plataforma.

Validación de las llamadas de retorno seguras

La validación de las llamadas de retorno seguras ofrece una serie de ventajas en materia de seguridad, entre las que se incluyen:

  • La capacidad de verificar que una solicitud proviene de Vonage

  • Garantizar que el mensaje no haya sido alterado durante su transmisión

  • Defensa contra la interceptación y la repetición posterior

La validación de las retrollamadas seguras consta de dos partes:

  • Verify la solicitud

  • Verificación de la carga útil (opcional)

Verify la solicitud

Las devoluciones de llamada incluirán un JWT en la cabecera de autorización. Utilice la clave de API incluida en las reclamaciones JWT para identificar cuál de sus secretos de firma se ha utilizado para firmar la solicitud. El secreto utilizado para firmar la solicitud se corresponde con el secreto de firma asociado a la api_key incluida en las reivindicaciones JWT. Puede identificar su secreto de firma a través de la función Portal de la cuenta API de Video de Vonage.

Verify the payload has not been tampered with in transit

Una vez que hayas verificado la autenticidad de la solicitud, puedes, si lo deseas, comprobar que la carga útil de la solicitud no haya sido alterada comparando un hash SHA-256 de la carga útil con el campo «payload_hash» que se encuentra en las reclamaciones del JWT. Si no coinciden, significa que la carga útil ha sido alterada durante la transmisión. Solo es necesario verificar la carga útil si se utiliza HTTP en lugar de HTTPS, ya que el protocolo TLS (Transport Layer Security) impide Ataques MITM.

Ejemplo de código

El siguiente ejemplo de Express muestra cómo verificar la firma de un webhook. Se recomienda utilizar el protocolo HTTPS, ya que garantiza que tanto la solicitud como la respuesta estén cifradas tanto en el lado del cliente como en el del 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'));

Limitaciones y consideraciones conocidas

La siguiente sección cubre las limitaciones y consideraciones antes de habilitar esta función.

Dirección IP de devolución de llamada

Una vez habilitadas las retrollamadas seguras, el rango de direcciones IP utilizado por el servicio de retrollamadas de Vonage será de un conjunto diferente al de las retrollamadas anteriores de Video API. Permite el siguiente rango para permitir una comunicación fluida con las devoluciones de llamadas seguras de Vonage: 216.147.0.0/18.

TLS mutuo (mTLS)

El flujo de callbacks seguros es compatible con mTLS. (Anteriormente, no lo era)

Cambios en la política de reintentos y retrasos de las llamadas de retorno

Una vez habilitada la función de callbacks seguros, se producirá un cambio en el comportamiento de la política de reintentos y retrasos de los callbacks.

Ten en cuenta que solo se realizan reintentos en caso de problemas de conectividad (no en caso de otros errores).

¿Qué pasará si los eventos de devolución de llamada de mi aplicación dejan de funcionar?

  • Comportamiento anterior: Vonage realizará 4 reintentos por cada evento que no se haya podido entregar al servidor de aplicaciones.

    Solo para la supervisión de sesiones: si la plataforma detecta 50 errores de entrega en un intervalo de 30 minutos, se desactivó el reenvío de eventos para las llamadas de retorno de la supervisión de sesiones. Se envió un correo electrónico de notificación al cliente para informarle de que se habían desactivado las devoluciones de llamada. Para volver a activar el reenvío de eventos, era necesario volver a configurar la URL de devolución de llamada de la supervisión de sesiones a través del portal de la cuenta de la Video API de Vonage.

  • Nuevo comportamiento: Transcurridas 24 horas, la lógica de reintentos de las llamadas de retorno individuales se detendrá y ya no se enviará el evento de llamada de retorno individual. No obstante, se seguirán intentando las llamadas de retorno para nuevos eventos.

Importante: En caso de que se produzcan un número excesivo de fallos en la entrega, el nuevo servicio ya no desactivará el reenvío de eventos, ya que se utilizará el mecanismo de reintentos y retrasos. Por lo tanto, ya no se enviará ningún correo electrónico para notificar que las respuestas automáticas se han desactivado y deben volver a activarse, ya que el nuevo servicio no suspenderá ni desactivará las respuestas automáticas en ningún caso.