Sichere Rückrufe

Sie können die Webhooks, die Sie für die Video API verwenden, so konfigurieren, dass sie durch signierte Callbacks gesichert sind.

Die Funktion „Sichere Callbacks“ bietet Ihrer Anwendung eine Möglichkeit, zu Verify, ob eine Webhook-Callback-Anfrage tatsächlich von Vonage stammt und deren Nutzdaten während der Übertragung nicht manipuliert wurden. Beim Empfang einer Anfrage enthält der eingehende Callback-Webhook im Autorisierungsheader ein JWT-Token, das mit Ihrem Signatur-Secret signiert ist.

Die folgenden API-Callbacks können durch signierte Callbacks gesichert und mit einem eigenen Signatur-Secret konfiguriert werden:

  • Überwachung von Sitzungen — Überwachen Sie die Sitzungsaktivitäten, indem Sie eine Callback-URL registrieren. Callback-Webhooks zur Sitzungsüberwachung werden an diese URL gesendet, sobald ein Sitzungsereignis erkannt wird.

  • Überwachung der Archivierung — Überwachen Sie den Archivstatus, indem Sie eine Callback-URL registrieren. Es werden Archiv-Callbacks gesendet, um Statusmeldungen zu Archivaufzeichnungen und den daraus resultierenden Dateien bereitzustellen.

  • SIP-Anrufüberwachung — Überwachen Sie die SIP-Anrufaktivität, indem Sie eine Callback-URL registrieren. Sobald ein SIP-Anrufereignis erkannt wird, wird eine HTTP-Anfrage an diese URL gesendet.

  • Broadcast-Überwachung — Überwachen Sie Broadcast-Aktivitäten, indem Sie eine Callback-URL registrieren. Callback-Ereignisse für Broadcasts werden gesendet, sobald ein Broadcast-Ereignis erkannt wird (beispielsweise wenn ein Broadcast erstellt, aktualisiert oder gelöscht wird).

  • Composer-Überwachung erleben — Überwachen Sie die Aktivitäten von Experience Composer, indem Sie eine Callback-URL registrieren. Callback-Ereignisse von Experience Composer werden gesendet, sobald sich der Status von Experience Composer ändert.

  • Live-Überwachung von Untertiteln — Überwachen Sie die Aktivitäten von „Live Captions“, indem Sie eine Callback-URL registrieren. Callback-Ereignisse von „Live Captions“ werden gesendet, wenn die Live-Untertitel starten, gestoppt werden oder ein Fehler auftritt.

Sichere Rückrufe konfigurieren

Mit den folgenden Anweisungen können Sie die Sitzungsüberwachung als sicheren Callback aktivieren. Sie können diese Anweisungen in ähnlicher Weise auch für andere Callbacks befolgen (für die Archivüberwachung, die SIP-Anrufüberwachung und die Experience-Composer-Überwachung).

  1. Melden Sie sich bei Ihrem Vonage Video API Account.

  2. Wählen Sie im Menü auf der linken Seite den gewünschten Account aus.

  3. Wählen Sie im Menü auf der linken Seite das Projekt aus, für das Sie einen sicheren Callback registrieren möchten.

  4. finden. Überwachung von Sitzungen (oder den entsprechenden Abschnitt) und klicken Sie auf Konfigurieren Sie.

  5. Die Benutzeroberfläche enthält Optionen zur Konfiguration der Callback-URL und (optional) eines Signatur-Schlüssels.

  6. Ein zufällig generiertes Signaturgeheimnis wird vom System jedes Mal bereitgestellt, wenn das Feld für das Signaturgeheimnis aktiviert wird. Dieser vorausgefüllte Wert des Signaturgeheimnisses kann verwendet oder mit einem vom Benutzer ausgewählten Wert überschrieben werden. Beim Empfang eines Rückrufs wird der eingehende Webhook mit dem in diesem Feld konfigurierten Signaturgeheimnis signiert. Klicken Sie auf . Absenden um dieses Geheimnis für sichere Callbacks zu konfigurieren. (Hinweis: Das Signaturgeheimnis muss eine Zeichenkette mit einer Mindestlänge von 1 Zeichen und einer Höchstlänge von 50 Zeichen sein.)

  7. Das System meldet, dass sichere Callbacks mit der URL und dem Signatur-Secret konfiguriert wurden. Bitte beachten Sie, dass es bis zu 30 Minuten dauern kann, bis die Konfiguration auf der Plattform übernommen wird.

Validierung sicherer Rückrufe

Die Validierung sicherer Rückrufe bringt eine Reihe von Sicherheitsvorteilen mit sich, darunter:

  • Die Möglichkeit zu verifizieren, dass eine Anfrage von Vonage stammt

  • Sicherstellung, dass die Nachricht während der Übermittlung nicht manipuliert wurde

  • Verteidigung gegen Abfangen und spätere Wiederholung

Die Validierung sicherer Rückrufe besteht aus zwei Teilen:

  • Verify der Anfrage

  • Verify der Nutzlast (optional)

Verify der Anfrage

Rückrufe enthalten ein JWT in der Autorisierungskopfzeile. Verwenden Sie den in den JWT-Anforderungen enthaltenen API-Schlüssel, um festzustellen, welches Ihrer Signaturgeheimnisse zum Signieren der Anforderung verwendet wurde. Das zum Signieren der Anforderung verwendete Geheimnis entspricht dem Signaturgeheimnis, das mit dem in den JWT-Ansprüchen enthaltenen api_key verbunden ist. Sie können Ihr Signaturgeheimnis über die Option Vonage Video API Account-Portal.

Verify, dass die Nutzlast während des Transports nicht manipuliert wurde

Sobald Sie die Echtheit der Anfrage verifiziert haben, können Sie optional sicherstellen, dass die Nutzdaten der Anfrage nicht manipuliert wurden, indem Sie einen SHA-256-Hash der Nutzdaten mit dem Feld „payload_hash“ in den JWT-Claims vergleichen. Stimmen diese nicht überein, wurden die Nutzdaten während der Übertragung manipuliert. Sie müssen die Nutzdaten nur Verify, wenn Sie HTTP anstelle von HTTPS verwenden, da Transport Layer Security (TLS) verhindert, dass MITM-Angriffe.

Code-Beispiel

Das folgende Express-Beispiel zeigt, wie man die Signatur eines Webhooks Verifyt. Es wird empfohlen, das HTTPS-Protokoll zu verwenden, da dadurch sichergestellt wird, dass die Anfrage und die Antwort sowohl auf Client- als auch auf Serverseite verschlüsselt sind.

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

Bekannte Beschränkungen/Berücksichtigungen

Der folgende Abschnitt behandelt Einschränkungen und Überlegungen vor der Aktivierung dieser Funktion.

IP-Adresse des Rückrufs

Nach der Aktivierung für sichere Rückrufe wird der vom Vonage-Rückrufdienst verwendete IP-Adressbereich ein anderer sein als bei früheren Video API-Rückrufen. Bitte erlauben Sie den folgenden Bereich, um eine nahtlose Kommunikation mit sicheren Vonage-Rückrufen zu ermöglichen: 216.147.0.0/18.

Gegenseitiges TLS (mTLS)

mTLS wird im Ablauf der sicheren Callbacks unterstützt. (Bisher war dies nicht der Fall.)

Änderungen an den Richtlinien für Wiederholungsversuche und Backoff-Verfahren bei Callbacks

Sobald sichere Rückrufe aktiviert sind, ändert sich das Verhalten bei der Wiederholung von Rückrufen und der Backoff-Politik.

Beachten Sie, dass Wiederholungsversuche nur bei Verbindungsproblemen unternommen werden (nicht bei anderen Fehlern).

Was passiert, wenn die Callback-Ereignisse meiner Anwendung ausfallen?

  • Bisheriges Verhalten: Vonage unternimmt vier Wiederholungsversuche für jedes Ereignis, das nicht an den Anwendungsserver übermittelt werden konnte.

    Nur für die Sitzungsüberwachung – Wenn die Plattform innerhalb eines Zeitraums von 30 Minuten 50 Übermittlungsfehler feststellt, wurde die Ereignisweiterleitung für Callbacks zur Sitzungsüberwachung deaktiviert. Dem Kunden wurde eine Benachrichtigungs-E-Mail gesendet, um ihn darüber zu informieren, dass die Callbacks deaktiviert wurden. Um die Ereignisweiterleitung wieder zu aktivieren, musste die Callback-URL für die Sitzungsüberwachung über das Vonage Video API-Account-Portal erneut konfiguriert werden.

  • Neues Verhalten: Nach 24 Stunden wird die Logik für die Wiederholung einzelner Callbacks beendet, und das jeweilige Callback-Ereignis wird nicht mehr gesendet. Callbacks für neue Ereignisse werden jedoch weiterhin versucht.

Das ist wichtig: Bei übermäßig vielen Zustellfehlern wird der neue Dienst die Weiterleitung von Ereignissen nicht mehr deaktivieren, da der Mechanismus für Wiederholungsversuche und Backoff zum Einsatz kommt. Daher wird es keine E-Mail-Benachrichtigung mehr geben, die darauf hinweist, dass Callbacks deaktiviert wurden und wieder aktiviert werden müssen, da der neue Dienst Callbacks in keiner Weise aussetzt oder deaktiviert.