Verificación de webhooks

Puede configurar el webhooks que utiliza para que Video API esté protegido con callbacks firmados.

La función de devolución de llamada segura ofrece un método para que tu aplicación verifique que una solicitud de devolución de llamada de webhook provenga de Vonage y que su carga útil no haya sido alterada durante el tránsito. Al recibir una solicitud, el webhook de devolución de llamada entrante incluirá un JWT en la cabecera de autorización, que está firmada con su secreto de firma.

Llamadas de retorno a la API disponibles

• Control de la sesión - Los webhook callbacks de monitorización de sesión serán enviados a la URL cuando se detecte un evento de Sesión.

• Supervisión del archivo - Se enviarán callbacks de archivo para proporcionar eventos de estado sobre las grabaciones de archivo y los ficheros resultantes

• Control de emisiones - Los eventos de devolución de llamada de difusión se enviarán cuando se detecte un evento de difusión (por ejemplo, cuando se cree, actualice o destruya una difusión).

• Experiencia de supervisión de Composer - Los eventos de devolución de llamada de Experience Composer se enviarán cuando cambie el estado de Experience Composer.

• Control de subtítulos en directo - Los eventos de devolución de llamada de los subtítulos en directo se envían cuando los subtítulos en directo se inician, se detienen y fallan.

• Supervisión de llamadas SIP - Se enviará una solicitud HTTP a la URL cuando se detecte un evento de llamada SIP

Configuración de retrollamadas seguras

1. Conéctese a su Cuenta de Video API de Vonage.

2. En el menú de la izquierda, seleccione Applications.

3. Para los proyectos existentes, haga clic en los tres puntos y seleccione la opción Editar y desplácese hasta la sección de capacidades.

4. Para los nuevos proyectos, la sección de capacidades se muestra después de hacer clic en Crear una nueva aplicación.

5. Activa la opción de vídeo.

6. Aparecerá un conjunto de entradas, cada una de las cuales ofrece devoluciones de llamada para diferentes partes de la API. Proporcione una URL adecuada para las entradas de devolución de llamada seleccionadas. Sólo entonces aparecerá una secreto de firma será conmutable. Haga clic en él para activar las retrollamadas.

El sistema proporcionará un secreto de firma generado aleatoriamente cada vez que se active el campo de secreto de firma. Este valor de secreto de firma precargado puede utilizarse o sobrescribirse con un valor seleccionado por el usuario. Al recibir una devolución de llamada, el webhook entrante se firmará con el secreto de firma configurado en el campo. Haga clic en Guardar cambios para configurar este secreto que se utilizará para las devoluciones de llamada seguras. (Nota: el secreto de firma debe ser una cadena de caracteres, con una longitud mínima de 1 carácter y máxima de 50 caracteres).

Puede activar tantas retrollamadas como desee.

Las actualizaciones de las URL y los secretos pueden tardar hasta 30 minutos en aplicar la configuración en la plataforma.

Validación de retrollamadas seguras

La validación de las retrollamadas seguras proporciona una serie de ventajas de seguridad, entre ellas:

• La capacidad de verificar que una solicitud proviene de Vonage

• Garantizar que el mensaje no ha sido manipulado durante el tránsito.

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

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

• Verificación de la solicitud

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

Verificación de 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.

Ejemplos de códigos

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'));

Limitaciones/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)

mTLS está soportado en el flujo de callbacks seguros. Más información aquí.

Cambios en la política de reintento de llamada y retroceso

Una vez habilitadas las retrollamadas seguras, se producirá un cambio en el comportamiento de la política de reintento de retrollamada y backoff.

¿Qué ocurrirá si los eventos callback de mi aplicación se caen?

Transcurridas 24 horas, la lógica de reintento de devolución de llamada individual se detendrá y el evento de devolución de llamada individual dejará de enviarse. Sin embargo, se seguirán intentando devoluciones de llamada para nuevos eventos.