Verify webhooks

Vous pouvez configurer le webhooks que vous utilisez pour l'API Video afin qu'elle soit sécurisée par des rappels signés.

La fonction de rappel sécurisé permet à votre application de vérifier qu'une demande de rappel de webhook provient bien de Vonage et que sa charge utile n'a pas été altérée pendant le transport. Lors de la réception d'une demande, le webhook de rappel entrant inclura une balise JWT dans l'en-tête d'autorisation, qui est signé avec votre secret de signature.

Rappels d'API disponibles

• Suivi de la session - Les rappels du webhook de surveillance de la session seront envoyés à l'URL lorsqu'un événement de session est détecté.

• Suivi de l'archivage - Des rappels d'archives seront envoyés pour fournir des événements d'état sur les enregistrements d'archives et les fichiers résultants.

• Surveillance de la radiodiffusion - Les événements de rappel de diffusion sont envoyés lorsqu'un événement de diffusion est détecté (par exemple, lorsqu'une diffusion est créée, mise à jour ou détruite).

• Expérience de la surveillance de Composer - Les événements de rappel du compositeur d'expérience seront envoyés lorsque le statut du compositeur d'expérience changera.

• Contrôle des sous-titres en direct - Les événements de rappel des sous-titres en direct sont envoyés lorsque les sous-titres en direct démarrent, s'arrêtent ou échouent.

• Surveillance des appels SIP - Une requête HTTP est envoyée à l'URL lorsqu'un appel SIP est détecté.

Configuration des rappels sécurisés

1. Connectez-vous à votre Video API Account de Vonage.

2. Dans le menu de gauche, sélectionnez Applications.

3. Pour les projets existants, cliquez sur les trois points et sélectionnez l'option Editer et faites défiler la page jusqu'à la section des capacités.

4. Pour les nouveaux projets, la section des capacités s'affiche après avoir cliqué sur Créer une nouvelle application.

5. Basculer pour activer l'option vidéo.

6. Une série d'entrées apparaîtra, chacune offrant des rappels pour différentes parties de l'API. Fournissez une URL appropriée pour les entrées de rappel sélectionnées. Ce n'est qu'à ce moment-là qu'un secret de signature devient basculant. Cliquez dessus pour activer les rappels.

Un secret de signature généré de manière aléatoire est fourni par le système chaque fois que le champ du secret de signature est activé. Cette valeur de secret de signature pré-remplie peut être utilisée ou remplacée par une valeur sélectionnée par l'utilisateur. Lors de la réception d'un rappel, le webhook entrant sera signé avec le secret de signature configuré dans le champ. Cliquez sur Enregistrer les modifications pour configurer le secret à utiliser pour les rappels sécurisés. (Note : le secret de signature doit être une chaîne de caractères, d'une longueur minimale de 1 caractère et d'une longueur maximale de 50 caractères).

Vous pouvez activer autant de rappels que vous le souhaitez.

Les mises à jour des URL et des secrets peuvent prendre jusqu'à 30 minutes pour appliquer la configuration dans la plateforme.

Validation des rappels sécurisés

La validation des rappels sécurisés offre un certain nombre d'avantages sur le plan de la sécurité, notamment :

• La possibilité de vérifier qu'une demande provient de Vonage

• S'assurer que le message n'a pas été altéré pendant son acheminement

• Défense contre l'interception et le rejeu ultérieur

La validation des rappels sécurisés se fait en deux temps :

• Verify the request

• Verify the payload (optionnel)

Verify the request

Les rappels incluront un JWT dans l'en-tête d'autorisation. Utilisez la clé API incluse dans les revendications JWT pour identifier lequel de vos secrets de signature a été utilisé pour signer la demande. Le secret utilisé pour signer la demande correspond au secret de signature associé à la clé api_key incluse dans les revendications JWT. Vous pouvez identifier votre secret de signature à l'aide de la fonction Portail du compte Video API de Vonage.

Exemples de code

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

Limitations/considérations connues

La section suivante traite des limitations et des considérations à prendre en compte avant d'activer cette fonctionnalité.

Adresse IP de rappel

Une fois les rappels sécurisés activés, la plage d'adresses IP utilisée par le service de rappel de Vonage sera différente de celle des précédents rappels de l'API Video. Veuillez autoriser la plage suivante pour permettre une communication transparente avec les rappels sécurisés de Vonage : 216.147.0.0/18.

TLS mutuel (mTLS)

mTLS est pris en charge dans le flux de rappels sécurisés. Pour plus d'informations, voir ici.

Modifications de la politique de rappel et d'annulation

Une fois que les rappels sécurisés sont activés, le comportement des tentatives de rappel et de la politique d'annulation des rappels change.

Que se passera-t-il si les événements de rappel de mon application tombent en panne ?

Au bout de 24 heures, la logique de rappel individuel s'arrête et l'événement de rappel individuel n'est plus envoyé. Toutefois, les rappels pour de nouveaux événements continueront d'être tentés.