仕様 | Webhook β版｜ユーザーガイド｜ SkyWay（スカイウェイ）

戻る

Webhook β版

Markdown形式で表示

検証リクエスト

検証リクエストは Webhook 機能にイベント送信先となるユーザーのサーバーのエンドポイントを設定するにあたって、Webhook 機能とユーザーのサーバーの双方でお互いが正当であることを確かめるための仕組みです。

ユーザーのサーバーは Webhook 機能から送信される検証リクエストに対して適切なレスポンスを返す必要があります。

検証リクエストは SkyWay コンソールで Webhook の設定を行うと送信されます。

そのため、SkyWay コンソールの操作前にユーザーのサーバーを Webhook 機能からアクセスできるように公開する必要があります。

検証リクエストのフォーマットは次の通りです。

項目	値
HTTP メソッド	`POST`

項目	値
ヘッダー
`Content-Type`	`application/json`
`X-SkyWay-Request-Timestamp`	`文字列(秒)`
`X-SkyWay-Signature`	`文字列(16進数)`
`User-Agent`	`SkyWay-Webhook/1.0.0 (+https://skyway.ntt.com/)`

項目	値
ボディ
`type`	`WEBHOOK_URL_VERIFICATION`
`appId`	`文字列(uuid)`
`timestamp`	`文字列(UTC/ISO 8601 形式)`
`data`	`{ "challenge": <uuid> }`
`schemaVersion`	`1`

必須

ユーザーのサーバーは次のフォーマットのレスポンスを 3 秒以内に行う必要があります

項目	値	補足
ステータスコード	2xx	200 OK を推奨
ボディ	文字列	プレーンテキストで `challenge` と完全一致する文字列（UTF-8 エンコーディング）
ヘッダー	任意	無視される

ユーザーのサーバーから適切なレスポンスが返されない場合（タイムアウト、エラーステータス、challenge の不一致など）、SkyWay Console での Webhook 設定が失敗します。この場合、サーバー側の実装を修正した後、再度 SkyWay Console から設定を行ってください。

推奨

署名を生成し、両者が一致するかどうかを確認することで検証リクエストの送信元が本物のSkyWayのWebhook機能であることを確かめることができます。これを署名の検証と呼びます。

検証リクエストの送信元が本物の SkyWay の Webhook 機能であることを確かめるために、X-SkyWay-Signature ヘッダーの値と、リクエストのボディを使って生成した署名が一致することを確認してください。これにより、検証リクエストの送信元が本物の SkyWay の Webhook 機能であることを確認できます。

詳細な検証方法については署名の検証をご参照ください。

Webhook リクエスト

Webhook 機能からユーザーのサーバーにイベントを送信するリクエストのフォーマットは次の通りです。

項目	値
HTTP メソッド	`POST`
ヘッダー
`Content-Type`	`application/json`
`X-SkyWay-Request-Timestamp`	`文字列(秒)`
`X-SkyWay-Signature`	`文字列(16進数)`
`User-Agent`	`SkyWay-Webhook/1.0.0 (+https://skyway.ntt.com/)`
ボディ
`type`	`文字列`
`appId`	`文字列(uuid)`
`timestamp`	`文字列`
`data`	`文字列(JSONオブジェクト)`
`schemaVersion`	`1`

必須

ユーザーのサーバは次のフォーマットのレスポンスを 3 秒以内に行う必要があります。

制限時間内にレスポンスが行われない場合、Webhook 機能はリクエストをリトライします。

項目	値	補足
ステータスコード	2xx	200 OK を推奨
ボディ	任意	無視される。サイズが 1KiB を越えるとレスポンスに失敗する
ヘッダー	任意	無視される

推奨

検証リクエストと同様に送信元が本物の SkyWay の Webhook 機能であることを確かめるために、X-SkyWay-Signature ヘッダーの値と、リクエストのボディを使って生成した署名が一致することを確認してください。

またリプレイ攻撃を防止するために必要に応じてタイムスタンプを検証することも可能です。

通知イベント

録音・録画のイベント

録音・録画のイベントのtype名には「RECORDING_」という接頭辞が付きます。

録音・録画の開始

録音・録画ファイルの作成を開始した時に次のような形式で通知されるイベントです。

録音・録画可能な時間の制限の、録音・録画の最小時間を満たしたファイルのみがイベント通知の対象となります。

録音・録画を開始したファイルの状態の変化を追跡するために data.file.path を識別子として利用することができます。

{
  type: "RECORDING_FILE_STARTED";
  appId: string;
  data: {
    session: {
      id: string;
      roomId: string;
    };
    file: {
      name: string;
      path: string;
      status: "RECORDING" | "SUCCEEDED" | "FAILED";
      errors: {
        detail: string;
        occurredAt: string;
      }[];
      type: "AUDIO" | "VIDEO" | "AUDIO_AND_VIDEO";
      createdAt: string;
      codecs: string[];
      duration: number;
      publisher: {
        name?: string;
        id: string;
      };
      publications: {
        id: string;
        publisher: {
          name?: string;
          id: string;
        };
        contentType: "AUDIO" | "VIDEO";
      }[];
    };
  };
  timestamp: string;
}

録音・録画の完了

録音・録画が正常に完了した時に通知されるイベントです。

type は RECORDING_FILE_SUCCEEDED で、type 以外 RECORDING_FILE_STARTED と同じ形式です。

録音・録画の強制終了

回復不能なエラーによって録音・録画が強制的に終了された時に通知されるイベントです。

type は RECORDING_FILE_FAILED で、type 以外 RECORDING_FILE_STARTED と同じ形式です。

録音・録画が強制終了された際の対処方法についてはエラーとなった場合の録音・録画ファイルの取得を参考にしてください。

録音・録画のエラーが発生

すべてのエラーの発生時に通知されるイベントです。

type は RECORDING_FILE_ERROR_OCCURRED で、type 以外 RECORDING_FILE_STARTED と同じ形式です。

Webhook の詳細仕様

Webhook 機能のイベント通知のリトライについて

ユーザーのサーバーが一時的にイベントの通知ができない状況に対応するために Webhook 機能はイベント通知のリトライを行います。リトライの仕様は次の通りです。

リトライ対象のステータスコード
- 429
- 500~599
最大試行時間: 3 日 (259200 秒)

最大試行時間の間にバックオフリトライします。

注意事項

通知順序

概ねイベントの発生時刻の通り通知されますが、完全な順序保証はされていません。

重複通知

ごく稀に内容の重複したイベントが通知されることがあります。

通知が重複することで致命的な事態が生じないように必要に応じて対策を講じる必要があります。

イベント通知の欠損

Webhook 機能はほとんどのケースにおいて Webhook リクエストを送信しますが、ごく稀に Webhook リクエストが欠損する可能性があります。全てのイベント情報が、Webhook リクエストとして必ず送信される保証は無い点にご留意ください。

クイックスタート

開発ガイド