Webhooks verifizieren

Sie können die Webhaken die Sie für Video API verwenden, mit signierten Rückrufen gesichert werden.

Mit der Funktion "Sichere Rückrufe" kann Ihre Anwendung verifizieren, dass eine Webhook-Rückrufanforderung von Vonage stammt und die Nutzdaten während der Übertragung nicht manipuliert wurden. Beim Empfang einer Anfrage enthält der eingehende Callback-Webhook eine JWT im Autorisierungskopf, der mit Ihrem Signaturgeheimnis signiert ist.

Verfügbare API-Aufrufe

• Überwachung von Sitzungen - Webhook-Rückrufe zur Sitzungsüberwachung werden an die URL gesendet, wenn ein Sitzungsereignis erkannt wird.

• Überwachung der Archivierung - Archiv-Callbacks werden gesendet, um Statusereignisse zu Archivaufzeichnungen und den daraus resultierenden Dateien zu liefern

• Broadcast-Überwachung - Broadcast-Callback-Ereignisse werden gesendet, wenn ein Broadcast-Ereignis erkannt wird (z. B. wenn ein Broadcast erstellt, aktualisiert oder zerstört wird).

• Composer-Überwachung erleben - Callback-Ereignisse des Experience Composers werden gesendet, wenn sich der Status des Experience Composers ändert.

• Live-Überwachung von Untertiteln - Live-Untertitel-Callback-Ereignisse werden gesendet, wenn Live-Untertitel starten, stoppen und fehlschlagen.

• SIP-Anrufüberwachung - Eine HTTP-Anfrage wird an die URL gesendet, wenn ein SIP-Anrufereignis erkannt wird.

Sichere Rückrufe konfigurieren

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

2. Wählen Sie im Menü auf der linken Seite Applications.

3. Bei bestehenden Projekten klicken Sie auf die drei Punkte und wählen die bearbeiten und blättern Sie nach unten zum Abschnitt Fähigkeiten.

4. Bei neuen Projekten wird der Abschnitt Fähigkeiten angezeigt, nachdem Sie auf Erstellen Sie eine neue Anwendung.

5. Umschalten, um die Videooption zu aktivieren.

6. Es wird eine Reihe von Eingängen angezeigt, die jeweils Rückrufe für verschiedene Teile der API anbieten. Geben Sie eine geeignete URL für die ausgewählten Callback-Eingänge an. Nur dann wird eine Unterschriftsgeheimnis Schaltfläche wird umschaltbar. Klicken Sie darauf, um die Rückrufe zu aktivieren.

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 . Änderungen speichern um dieses Geheimnis zu konfigurieren, das für sichere Rückrufe verwendet werden soll. (Hinweis: Das Signaturgeheimnis muss eine Zeichenkette sein, mit einer Mindestlänge von 1 Zeichen und einer Höchstlänge von 50 Zeichen).

Sie können so viele Rückrufe aktivieren, wie Sie möchten.

Die Aktualisierung der URLs und Geheimnisse kann bis zu 30 Minuten dauern, bis die Konfiguration in 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.

Code-Beispiele

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

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 Fluss der sicheren Rückrufe unterstützt. Weitere Informationen finden Sie unter hier.

Rückrufwiederholung und Änderungen der Rückrufpolitik

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

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

Nach 24 Stunden wird die Logik zur Wiederholung einzelner Rückrufe beendet und das einzelne Rückrufereignis wird nicht mehr gesendet. Es werden jedoch weiterhin Rückrufe für neue Ereignisse versucht.