Rappels sécurisés

Vous pouvez configurer les webhooks que vous utilisez pour la Video API afin qu'ils soient sécurisés à l'aide de callbacks signés.

La fonctionnalité de callbacks sécurisés permet à votre application de vérifier qu’une requête de callback via webhook provient bien de Vonage et que sa charge utile n’a pas été altérée pendant le transfert. Lors de la réception d’une requête, le webhook de callback entrant inclura un jeton JWT dans l’en-tête d’autorisation, signé à l’aide de votre clé secrète de signature.

Les callbacks API suivants peuvent être sécurisés à l'aide de callbacks signés et configurés avec leur propre clé de signature :

  • Suivi de la session — Surveillez l'activité des sessions en enregistrant une URL de rappel. Les rappels via webhook de surveillance des sessions seront envoyés à cette URL lorsqu'un événement de session sera détecté.

  • Suivi de l'archivage — Surveillez l'état de l'archivage en enregistrant une URL de rappel. Des notifications de rappel concernant l'archivage seront envoyées pour vous informer des événements liés aux enregistrements archivés et aux fichiers générés.

  • Surveillance des appels SIP — Surveillez l'activité des appels SIP en enregistrant une URL de rappel. Une requête HTTP sera envoyée à cette URL lorsqu'un événement d'appel SIP sera détecté.

  • Surveillance de la radiodiffusion — Surveillez l'activité de diffusion en enregistrant une URL de rappel. Des événements de rappel de diffusion seront envoyés lorsqu'un événement de diffusion sera détecté (par exemple, lorsqu'une diffusion est créée, mise à jour ou supprimée).

  • Expérience de la surveillance de Composer — Surveillez l'activité d'Experience Composer en enregistrant une URL de rappel. Les événements de rappel d'Experience Composer seront envoyés lorsque l'état d'Experience Composer changera.

  • Contrôle des sous-titres en direct — Surveillez l'activité de « Live Captions » en enregistrant une URL de rappel. Les événements de rappel de « Live Captions » sont envoyés lorsque les sous-titres en direct démarrent, s'arrêtent ou rencontrent un problème.

Configuration des rappels sécurisés

Les instructions suivantes permettent d'activer la surveillance des sessions via un callback sécurisé. Vous pouvez également suivre ces instructions de la même manière pour d'autres callbacks (pour la surveillance des archives, la surveillance des appels SIP et la surveillance d'Experience Composer).

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

  2. Dans le menu de gauche, sélectionnez l’Account souhaité.

  3. Dans le menu de gauche, sélectionnez le projet pour lequel vous souhaitez enregistrer un rappel sécurisé.

  4. Trouver Suivi de la session (ou la rubrique correspondante) puis cliquez sur Configurer.

  5. L'interface utilisateur propose des options permettant de configurer l'URL de rappel et (éventuellement) une clé secrète de signature.

  6. 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 Envoyer pour configurer ce secret afin qu'il soit utilisé pour les rappels sécurisés. (Remarque : le secret de signature doit être une chaîne de caractères, d'une longueur comprise entre 1 et 50 caractères.)

  7. Le système indiquera que les callbacks sécurisés ont été configurés avec l'URL et la clé de signature. Veuillez noter que la mise en œuvre de la configuration sur la plateforme peut prendre jusqu'à 30 minutes.

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.

Verify que la charge utile n'a pas été altérée en cours de route

Une fois que vous avez vérifié l'authenticité de la requête, vous pouvez, si vous le souhaitez, vérifier que le contenu de la requête n'a pas été altéré en comparant le hachage SHA-256 de ce contenu au champ « payload_hash » figurant dans les revendications du JWT. S'ils ne correspondent pas, cela signifie que le contenu a été altéré pendant le transfert. Vous ne devez vérifier la charge utile que si vous utilisez HTTP plutôt que HTTPS, car le protocole TLS (Transport Layer Security) empêche Attaques MITM.

Exemple de code

L'exemple Express suivant montre comment vérifier la signature d'un webhook. Il est recommandé d'utiliser le protocole HTTPS, car celui-ci garantit que la requête et la réponse sont chiffrées tant du côté client que du côté serveur.

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

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)

Le protocole mTLS est désormais pris en charge dans le flux des callbacks sécurisés. (Ce n'était pas le cas auparavant.)

Modifications apportées à la politique de relance et de délai d'attente des rappels

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.

Notez que les tentatives de réessai ne sont effectuées qu'en cas de problèmes de connexion (et non pour d'autres erreurs).

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

  • Comportement antérieur : Vonage effectuera 4 tentatives pour chaque événement que nous ne parvenons pas à transmettre au serveur d'application.

    Pour la surveillance des sessions uniquement – Si la plateforme détecte 50 échecs de transmission au cours d'une période de 30 minutes, le transfert d'événements est désactivé pour les rappels de surveillance des sessions. Un e-mail de notification a été envoyé au client pour l'informer que les rappels avaient été désactivés. Pour réactiver le transfert d'événements, l'URL de rappel de la surveillance de session devait être reconfigurée via le portail de compte de la Video API Vonage.

  • Nouveau comportement : au bout de 24 heures, la logique de réessai des callbacks individuels s'arrêtera et l'événement de callback individuel ne sera plus envoyé. En revanche, les tentatives de callback pour les nouveaux événements se poursuivront.

Important : En cas d'échecs de livraison trop fréquents, le nouveau service ne désactivera plus le transfert d'événements, car il utilisera un mécanisme de réessai et de temporisation. Par conséquent, aucun e-mail ne sera envoyé pour signaler que les rappels ont été désactivés et doivent être réactivés, car le nouveau service ne suspendra ni ne désactivera les rappels en aucune manière.