ウェブフックの検証

を設定することができます。ウェブフックを使用する場合は、Video API を署名付きコールバックで保護する必要があります。

セキュアコールバック機能は、WebhookコールバックリクエストがVonageからのものであり、そのペイロードが転送中に改ざんされていないことをアプリケーションが確認する方法を提供します。リクエストを受信すると、受信コールバックWebhookには JWT このヘッダはあなたの署名シークレットで署名される。

利用可能なAPIコールバック

セッション・モニタリング - セッションイベントが検出されると、セッション監視ウェブフックコールバックが URL に送信されます。
アーカイブ監視 - アーカイブ・コールバックが送信され、アーカイブ録画とその結果のファイルに関するステータス・イベントが提供される。
ブロードキャスト・モニタリング - ブロードキャスト・コールバック・イベントは、ブロードキャスト・イベントが検出されたとき（たとえば、ブロードキャストが作成、更新、破棄されたとき）に送信されます。
エクスペリエンス・コンポーザーのモニタリング - エクスペリエンス・コンポーザーのステータスが変更されると、エクスペリエンス・コンポーザーのコールバック・イベントが送信されます。
ライブ・キャプション・モニタリング - ライブキャプションコールバックイベントは、ライブキャプションが開始、停止、失敗したときに送信されます。
SIPコールモニタリング - SIPコールイベントが検出されると、HTTPリクエストがURLに送信される。

安全なコールバックの設定

ログイン Vonage Video API アカウント.
左側のメニューから Applications.
既存のプロジェクトについては、3つの点をクリックして編集オプションを選択し、ケイパビリティ・セクションまでスクロールダウンする。
新規プロジェクトの場合、以下のボタンをクリックすると、ケイパビリティ・セクションが表示されます。 新規アプリケーションの作成.
トグルでビデオオプションを有効にする。
入力のセットが表示され、それぞれがAPIの異なる部分のコールバックを提供する。選択したコールバック入力に適切なURLを提供する。そのときだけ 署名の秘密 ボタンが切り替え可能になる。クリックするとコールバックが有効になります。

署名秘密フィールドが有効になるたびに、ランダムに生成された署名秘密がシステムから提供される。この事前に入力された署名の秘密の値は、使用することも、ユーザーが選択した値で上書きすることもできます。コールバックを受信すると、受信したウェブフックはフィールドに設定された署名秘密で署名されます。をクリックします。 変更を保存する を使用して、セキュアなコールバックに使用されるこの秘密を設定します。(注意: 署名の秘密は文字列でなければならない。長さは最小1文字から最大50文字まで)。

コールバックはいくつでも有効にできる。

URLとシークレットの更新は、プラットフォームへの設定適用に最大30分かかる場合があります。

安全なコールバックの検証

セキュアなコールバックを検証することで、以下のようなセキュリティ上の利点がある：

リクエストがVonageから発信されたものであることを確認する機能
転送中にメッセージが改ざんされていないことの確認
インターセプトとリプレーに対するディフェンス

安全なコールバックの検証には2つの部分がある：

リクエストの検証
ペイロードの検証（オプション）

リクエストの検証

コールバックはAuthorizationヘッダーにJWTを含む。JWTクレームに含まれるAPIキーを使用して、どの署名秘密がリクエストに署名するために使用されたかを識別する。リクエストに署名するために使用される秘密鍵は、JWTクレームに含まれるapi_keyに関連付けられた署名秘密鍵に対応する。署名の秘密は Vonage Video API アカウントポータル.

コードサンプル

以下の例では、以下の方法でウェブフック署名を Verify しています。 Vonage JWT ライブラリを使用してください。HTTPSプロトコルは、リクエストとレスポンスがクライアント側とサーバー側の両方で確実に暗号化されるため、使用することを推奨する。

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

以下の例では、以下の方法でウェブフック署名を Verify しています。 jsonwebtoken そして sha256 ライブラリを使用します。HTTPSプロトコルは、リクエストとレスポンスがクライアント側とサーバー側の両方で確実に暗号化されるため、使用することを推奨する。

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

既知の制限／考慮事項

次のセクションでは、この機能を有効にする前の制限と考慮事項について説明します。

コールバックIPアドレス

セキュアコールバックを有効にすると、Vonageコールバックサービスで使用されるIPアドレスの範囲は、以前のVideo APIコールバックとは異なります。Vonageセキュアコールバックとのシームレスな通信を可能にするには、以下の範囲を許可してください： 216.147.0.0/18.

相互TLS (mTLS)

mTLSはセキュアコールバックフローでサポートされている。詳細は以下を参照のこと。これ.

コールバック・リトライとバックオフ・ポリシーの変更

セキュアコールバックを有効にすると、コールバックの再試行とバックオフポリシーの動作が変更される。

アプリケーションのコールバックイベントがダウンしたらどうなりますか？

24時間後、個別コールバックの再試行ロジックは停止し、個別コールバックイベントは送信されなくなる。しかし、新しいイベントのコールバックは試行され続けます。

重要だ： リトライとバックオフメカニズムが使用されるため、セッション監視サービスは、過剰な配信失敗の場合に（以前のバージョンのように）イベント転送を無効にしなくなりました。サービスが中断されたり無効になったりしないので、セッション監視コールバックの中断に関するメールを受け取ることはなくなりました。