イベントウェブフック

概要

Sora は、予め設定しておいた URL に、シグナリングの接続や切断、 録画の開始や終了といった様々なイベントを HTTP リクエストとして送信するウェブフックの機能を持っています。

この機能を使うことで、Sora のイベントをアプリケーション側と簡単に連携できます。

注意

sora.conf の event_webhook_url を有効にしない場合でも log/event_webhook.jsonl は生成されます。

ログ

イベントウェブフックのログは log/event_webhook.jsonl と log/event_webhook_error.jsonl に出力されます。 これは event_webhook_url を指定していなくても出力されます。

event_webhook.jsonl

イベントウェブフックで送信した すべて の処理を書き込みます。

event_webhook_error.jsonl

イベントウェブフックの送信が正常に処理できなかった処理を書き込みます。

• ステータスコードが 200 番台以外の場合

• タイムアウトした場合

設定

event_webhook_url

デフォルト:

未設定

イベントウェブフックリクエスト送信先の URL です。イベントウェブフック機能を利用する場合は指定してください。

この URL には HTTP または HTTPS の URL を指定することができます。

HTTPS の URL を指定する場合、リクエスト送信先のアプリケーションについて基本的には正規の認証局から発行された証明書を利用してください。

独自の証明書を利用する場合は ウェブフックリクエスト送信先のサーバーが自己発行証明書などを利用している場合 をご確認ください。

HTTP のレスポンスは 200 OK 等の 200 番台のステータスコードの必要があります。

connection_updated_webhook_interval

デフォルト:

1 min

イベントウェブフック connection.updated の送信間隔を設定します。設定は分単位 (min) のみで行えます。

詳細は connection_updated_webhook_interval をご確認ください。

ignore_connection_updated_webhook

デフォルト:

false

イベントウェブフック connection.updated の送信有無を設定します。

詳細は ignore_connection_updated_webhook をご確認ください。

接続イベント

• connection.created と connection.destroyed はセットです

• connection.created がリクエスト送信されずに connection.destroyed がリクエスト送信されることはありません

• connection.created がリクエスト送信された場合、 connection.destroyed が 必ず リクエスト送信されます

• connection.created の後に connection.destroyed がリクエスト送信されます。順番は保証されます

共通項目

• id

  • イベントごとの ID です

• version

  • Sora のバージョンが 文字列 で入ってきます

• label

  • sora.conf の label で指定した値が入ってきます

• node_name

  • Sora のノード名が入ってきます

• log_written

  • イベントウェブフックログの書き込みが成功したかどうかが入ってきます

  • 書き込みが成功した場合は true が入ってきます

• minutes

  • 接続経過時間 (分) が入ってきます

• created_time

  • connection.created 時の時間が UNIX 時間形式で入ってきます

  • 例: 1704067199

• created_timestamp

  • connection.created 時の時間が RFC 3339 UTC 形式 (マイクロ秒) で入ってきます

  • 例: 2023-12-31T23:59:59.999999Z

• total_received_bytes

  • Sora がクライアントから受信したパケットの合計数です

• total_sent_bytes

  • Sora がクライアントへ送信したパケットの合計数です

• turn_transport_type

  • udp か tcp が入ってきます

  • TURN-UDP または TURN-TCP (TURN-TLS 含む) のどちらを使用したかがわかります

• audio

  • true または false が入ってきます

  • false の場合は audio を使用しません

• audio_codec_type

  • この項目はオプションです

  • audio が false の場合は含まれません

  • コーデックの種類は OPUS です

• audio_bit_rate

  • この項目はオプションです

  • audio が false やクライアントが送ってこない場合、含まれません

  • この設定は audio_codec_type が OPUS の時のみ有効です

  • default_audio_bit_rate に値を指定していた場合はその値が利用されます

  • 最小が 6 で、最大が 510 です

  • 単位は kbps です

• video

  • true または false が入ってきます

  • false の場合は video を使用しません

• video_codec_type

  • この項目はオプションです

  • video が false の場合は含まれません

  • コーデックはクライアントが送ってこない場合はデフォルトで VP9 が使用されます

  • コーデックの種類は VP8、 VP9、 AV1、 H264、 H265 です

• video_bit_rate

  • この項目はオプションです

  • video が false の場合は含まれません

  • ビットレートはクライアントが送ってこない場合は sora.conf の default_video_bit_rate が使用されます

  • デフォルトは 500 です

  • 最小が 1 で、最大が 30000 です

  • 15000 より大きい値は現時点でサポート範囲外です

  • 単位は kbps です

• video_vp9_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの VP9 設定指定 をご確認ください

• video_av1_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの AV1 設定指定 をご確認ください

• video_h264_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの H.264 設定指定 をご確認ください

• video_h265_params

  • この項目はオプションです

  • video が false の場合は含まれません

  • 詳細は ビデオの H.265 設定指定 をご確認ください

• multistream

  • true の場合はマルチストリームが有効な接続です

• simulcast

  • true の場合はサイマルキャストが有効な接続です

• simulcast_multicodec

  • この項目はオプションです

  • true の場合はサイマルキャストでマルチコーデックが有効な接続です

• spotlight

  • true の場合はスポットライトが有効な接続です

• role

  • sendrecv (送受信) / sendonly (送信のみ) / recvonly (受信のみ)

• event_metadata

  • この項目はオプションです

  • サーバーが定義を自由にできる値です

  • 認証サーバーから event_metadata を返した値が含まれます

  • 詳細は event_metadata の払い出し をご確認ください

• channel_id

  • コネクションが接続しているチャネル ID です

• session_id

  • コネクションが接続しているチャネル の現在のセッションの ID です

  • UUIDv4 を Base32 でエンコードした 26 バイトの文字列です

• client_id

  • コネクションに割り当てられたクライアント ID です

• bundle_id

  • コネクションに割り当てられたバンドル ID です

• connection_id

  • コネクションに割り当てられたユニークな ID です

  • UUIDv4 を Base32 でエンコードした 26 バイトの文字列です

• ice_connection_state

  • total_checking_duration_ms

    • ICE 接続の状態が checking になった時間の合計 (ミリ秒) です

  • total_disconnected_duration_ms

    • ICE 接続の状態が disconnected になった時間の合計 (ミリ秒) です

• recording_block

  • 録画(セッション単位)時に録画をブロックするかどうかが入ってきます

  • true であれば録画をブロックします

  • false であれば録画をブロックしません

connection.created

接続

シグナリングの接続が成功して、WebRTC としての通信が開始できるようになった時の状態を送信します。

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分は含まれます

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分は含まれます

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分は含まれます

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分は含まれます

{
  "type": "connection.created",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON Object>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "minutes": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.destroyed

切断

シグナリングの接続が切断した時に送信します。

• data.type_disconnect_reason

  • クライアントから "type": "disconnect" シグナリングメッセージに "reason" が項目に含まれていた際、その 文字列 が入ります

  • シグナリングメッセージに "reason" が含まれていなかった場合、この項目は含まれません

• data.disconnect_api_reason

  • DisconnectChannel API または DisconnectConnection API を利用して切断した際、オプションの "reason" に指定した JSON オブジェクト がこの "reason" に含まれます

  • "reason" を指定されていなかった場合、この項目は含まれません

• data.reason

  • コネクションが破棄された理由が含まれます

    • この値は常に含まれます

    • "normal" は通常のコネクション破棄

    • "disconnected_api" シグナリング切断系 API でのコネクション破棄

    • "session_destroyed" セッションライフタイム期限切れ、または TerminateSession API によるセッションの強制破棄でのコネクション破棄

    • "lifetime_expired" ライフタイム期限切れによるコネクション破棄

  • legacy_event_webhook_connection_destroyed_reason が true の場合は以下のような挙動になります

    • 基本的には data.disconnect_api_reason と同様です

    • ただし "reason" を指定していなかった場合に、項目が省略されるのではなく、値に null が入る点が異なっています

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分は含まれません

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分は含まれません

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分は含まれません

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分は含まれません

• data.destroyed_time

  • connection.destroyed 時の時間が UNIX 時間形式で入ってきます

• data.destroyed_timestamp

  • connection.destroyed 時の時間が RFC 3339 UTC 形式 (マイクロ秒) で入ってきます

{
  "type": "connection.destroyed",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON Object>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "destroyed_time": "<UNIX-Time>",
    "destroyed_timestamp": "<UTC RFC3339 Timestamp>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "minutes": "<Integer>",
    "reason": "<String>",
    "type_disconnect_reason": "<String>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Intger>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.updated

接続状態更新

注釈

このウェブフックリクエストの送信を停止することができます。 sora.conf の ignore_connection_updated_webhook を true にしてください。

connection.created を送信したタイミングから、クライアントごとの接続状態が、それぞれ一定間隔で送信されます。

送信間隔はデフォルトで 1 分です。 connection_updated_webhook_interval で送信間隔を変更できます。

• data.channel_connections

  • 現在そのチャネルに接続しているクライアントの接続数です

  • 自分が含まれます

• data.channel_sendrecv_connections

  • 現在そのチャネルで送受信している配信者の接続数です

  • 自分が含まれます

• data.channel_sendonly_connections

  • 現在そのチャネルを送信のみしている配信者の接続数です

  • 自分が含まれます

• data.channel_recvonly_connections

  • 現在そのチャネルを受信のみしている視聴者の接続数です

  • 自分が含まれます

{
  "type": "connection.updated",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "ice_connection_state": {
      "total_checking_duration_ms": "<Integer>",
      "total_disconnected_duration_ms": "<Integer>"
    },
    "recording_block": "<Boolean>",
    "audio": "<Boolean>",
    "audio_codec_type": "<String>",
    "channel_connections": ,
    "channel_recvonly_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "created_time": "<UNIX-Time>",
    "created_timestamp": "<UTC RFC3339 Timestamp>",
    "minutes": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>",
    "turn_transport_type": "<String>",
    "video": "<Boolean>",
    "video_bit_rate": "<Integer>",
    "video_codec_type": "<String>"
  },
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

connection.failed

接続失敗

重要

このイベントのログの出力やウェブフックを出力する場合、 sora.conf にて ignore_connection_failed_webhook を無効にする必要があります。

• connection.created の送信前に失敗や異常が起きた場合に送信されます

• connection.created の送信後に失敗や異常が起きた場合、 connection.destroyed が送信されます

{
  "type": "connection.failed",
  "id": "<Base32-UUIDv4>",
  "role": "<sendrecv | sendonly | recvonly>",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "message": "<String>",
    "channel_connections": "<Integer>",
    "channel_sendrecv_connections": "<Integer>",
    "channel_sendonly_connections": "<Integer>",
    "channel_recvonly_connections": "<Integer>",
    "total_received_bytes": "<Integer>",
    "total_sent_bytes": "<Integer>"
  },
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>",
  "version": "<String>"
}

録画・録音イベント

危険

このレガシー録画向けのイベントウェブフックは 2025 年 12 月に廃止されます。 録画機能 (セッション単位) への移行をお願いします。

重要

このイベントウェブフックは レガシー録画機能 利用時に送信します。

recording.started

重要

このイベントには event_metadata は含まれません

レガシー録画開始

• data.start_timestamp

  • StartRecording API を実行したタイムスタンプが入ります

• data.expire_time

  • StartRecording API で指定した expire_time が入ります

• data.expired_at

  • StartRecording API で指定した expire_time から計算した有効期限が入ります

• data.split_duration

  • この項目はオプションです

  • StartRecording API で指定した split_duration が入ります

  • 指定していない場合は split_duration の項目が入ってきません

• data.split_only

  • この項目はオプションです

  • StartRecording API で指定した split_only が入ります

  • 指定していない場合は false が入ります

• data.metadata

  • この項目はオプションです

  • StartRecording API で指定した metadata が入ります

  • 指定していない場合は metadata の項目が入ってきません

{
  "type": "recording.started",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "metadata": "<JSON-Object>",
    "split_only": "<Boolean>",
    "created_at": "<UNIX-Time>",
    "expire_time": "<Integer>",
    "expired_at": "<UNIX-Time>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "split_duration": "<Integer>"
  }
}

recording.report

重要

このイベントには event_metadata は含まれません

レガシー録画結果報告

• data.archives[].start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• data.archives[].stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

• data.metadata

  • StartRecording API で指定した metadata が入ります

  • 指定していない場合は metadata の項目が入ってきません

• data.expired_at

  • 期限が切れた日時を UNIX Time で返します

一括録画時 recording.report

{
  "type": "recording.report",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "metadata": "<JSON-Object>",
    "split_only": "<Boolean>",
    "created_at": "<UNIX-Time>",
    "expire_time": "<Integer>",
    "expired_at": "<UNIX-Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "file_written": "<Boolean>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "archives": [
      {
        "label": "<String>",
        "node_name": "<String>",
        "client_id": "<String | Base32-UUIDv4>",
        "bundle_id": "<String | Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "file_path": "<String>",
        "filename": "<String>",
        "metadata_file_path": "<String>",
        "metadata_filename": "<String>",
        "start_time_offset": "<Integer>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_time_offset": "<Integer>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
        "size": "<Integer>"
      },
      {
        "label": "<String>",
        "node_name": "<String>",
        "client_id": "<String | Base32-UUIDv4>",
        "bundle_id": "<String | Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "file_path": "<String>",
        "filename": "<String>",
        "metadata_file_path": "<String>",
        "metadata_filename": "<String>",
        "start_time_offset": "<Integer>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_time_offset": "<Integer>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
        "size": "<Integer>"
      }
    ],
    "failed_archives": [
      {
        "label": "<String>",
        "node_name": "<String>",
        "client_id": "<String | Base32-UUIDv4>",
        "bundle_id": "<String | Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>"
      },
      {
        "label": "<String>",
        "node_name": "<String>",
        "client_id": "<String | Base32-UUIDv4>",
        "bundle_id": "<String | Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>"
      }
    ]
  }
}

分割録画時 recording.report

{
  "type": "recording.report",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "metadata": "<JSON-Object>",
    "split_only": "<Boolean>",
    "split_duration": "<Integer>",
    "created_at": "<UNIX-Time>",
    "expire_time": "<Integer>",
    "expired_at": "<UNIX-Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "file_written": "<Boolean>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
    "archives": [
      {
          "label": "<String>",
          "node_name": "<String>",
          "client_id": "<String | Base32-UUIDv4>",
          "bundle_id": "<String | Base32-UUIDv4>",
          "connection_id": "<Base32-UUIDv4>",
          "start_time_offset": "<Integer>",
          "start_timestamp": "<UTC RFC3339 Timestamp>",
          "stop_time_offset": "<Integer>",
          "stop_timestamp": "<UTC RFC3339 Timestamp>",
          "split_last_index": "<String>"
      },
      {
          "label": "<String>",
          "node_name": "<String>",
          "client_id": "<String | Base32-UUIDv4>",
          "bundle_id": "<String | Base32-UUIDv4>",
          "connection_id": "<Base32-UUIDv4>",
          "start_time_offset": "<Integer>",
          "start_timestamp": "<UTC RFC3339 Timestamp>",
          "stop_time_offset": "<Integer>",
          "stop_timestamp": "<UTC RFC3339 Timestamp>",
          "split_last_index": "<String>"
      }
    ],
    "failed_archives": [
      {
          "label": "<String>",
          "node_name": "<String>",
          "client_id": "<String | Base32-UUIDv4>",
          "bundle_id": "<String | Base32-UUIDv4>",
          "connection_id": "<Base32-UUIDv4>"
      },
      {
          "label": "<String>",
          "node_name": "<String>",
          "client_id": "<String | Base32-UUIDv4>",
          "bundle_id": "<String | Base32-UUIDv4>",
          "connection_id": "<Base32-UUIDv4>"
      }
    ]
  }
}

録画・録音保存イベント

archive.started

録画ファイル保存開始

• data.start_timestamp

  • この録画が開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

{
  "type": "archive.started",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>"
  }
}

archive.available

録画保存ファイル出力

録画ファイルが出力されて利用できるようになったことを通知するウェブフックです。

• data.start_timestamp

  • この録画が開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • この録画が終了した時間(UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.start_time

  • この録画が開始された時間を UNIX 時間形式で表しています

• data.stop_time

  • この録画が終了した時間を UNIX 時間形式で表しています

• data.start_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が開始したかを表しています

• data.stop_time_offset

  • StartRecording API を叩いてから何秒経過した後にこの録画が終了したかを表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

{
  "type": "archive.available",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "metadata_file_path": "<String>",
    "metadata_filename": "<String>",
    "size": "<Integer>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
  }
}

split-archive.available

分割録画ファイル出力

分割録画ファイルが出力されて利用できるようになったことを通知するウェブフックです。

• data.split_index

  • 分割された録画ファイルのインデックス

  • 0001 から始まり 9999 までいったら、その後は 10000, 10001 と増えていきます

• data.start_timestamp

  • 分割して出力された録画ファイルを開始された時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • 分割して出力された録画ファイルを終了した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.start_time

  • 分割して出力された録画ファイルを開始した時間を UNIX 時間形式で表しています

• data.stop_time

  • 分割して出力された録画ファイルを終了した時間を UNIX 時間形式で表しています

• data.start_time_offset

  • この分割して出力された録画が、StartRecording API を叩いてから何秒経過した後に開始したかを表しています

• data.stop_time_offset

  • この分割して出力された録画が、StartRecording API を叩いてから何秒経過した後に終了したかを表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

{
  "type": "split-archive.available",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "channel_id": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "split_index": "<String>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "created_at": "<Unix Time>",
    "file_path": "<String>",
    "filename": "<String>",
    "metadata_file_path": "<String>",
    "metadata_filename": "<String>",
    "size": "<Integer>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {
    },
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
  }
}

注釈

stats は省略しています

split-archive.end

分割録画終了

分割録画ファイルが全て出力し終わったことを通知するウェブフックです。 このウェブフック以降は split-archive.available は送信されません。

• data.start_time

  • 録画を開始した UNIX 時間形式で表しています

• data.stop_time

  • 録画を終了した UNIX 時間形式で表しています

• data.start_timestamp

  • 録画を開始した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stop_timestamp

  • 録画を終了した時間 (UTC) を RFC 3339 形式 (マイクロ秒) で表しています

• data.stats

  • サポート向けに、録画に使用したパケット情報の統計を格納しています

  • 内部向け情報のため、予告なく変更されることがあります

{
  "type": "split-archive.end",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "event_metadata": "<JSON>",
  "data": {
    "split_last_index": "<String>",
    "recording_id": "<Base32-UUIDv4>",
    "channel_id": "<String>",
    "session_id": "<Base32-UUIDv4>",
    "client_id": "<String | Base32-UUIDv4>",
    "bundle_id": "<String | Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "file_path": "<String>",
    "filename": "<String>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_time_offset": "<Integer>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_time_offset": "<Integer>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
  }
}

archive.failed

録画ファイル保存失敗

このウェブフックが発生するのは、ディスク容量が足らなかったり、ディスクが故障してたり、 パーミッションにより書き込めなかった場合です。

単一録画、分割録画関係なくクライアントの録画ファイル保存に失敗した場合には発生し、クライアントの録画は停止されます。 書き込めない可能性がとても高いため、分割録画の場合でも録画はその時点で停止します。

もし問題を解決できた場合は、一度録画を停止し、再度録画を開始するようにしてください。

{
  "type": "archive.failed",
  "id": "<Base32-UUIDv4>",
  "version": "<String>",
  "label": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "event_metadata": "<JSON>",
  "data": {
    "recording_id": "<Base32-UUIDv4>",
    "session_id": "<Base32-UUIDv4>",
    "split": "<Boolean>",
    "split_only": "<Boolean>",
    "file_path": "<String>",
    "filename": "<String>",
    "audio": true,
    "audio_codec_type": "<String>",
    "video": true,
    "video_codec_type": "<String>",
    "video_bit_rate": "<Integer>",
    "video_height": "<Integer>",
    "video_width": "<Integer>",
    "stats": {},
    "start_time": "<Unix Time>",
    "start_timestamp": "<UTC RFC3339 Timestamp>",
    "stop_time": "<Unix Time>",
    "stop_timestamp": "<UTC RFC3339 Timestamp>",
  }
}

スポットライト機能

spotlight.focused

フォーカス設定

フォーカスされた際にウェブフックを送信します。

{
  "type": "spotlight.focused",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "spotlight_number:": "<Integer>",
  "fixed": "<Boolean>",
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "audio": "<Boolean>",
  "video": "<Boolean>"
}

spotlight.unfocused

フォーカス解除

フォーカスが外れた際にウェブフックを送信します。

{
  "type": "spotlight.unfocused",
  "channel_id": "<String>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "spotlight_number:": "<Integer>",
  "audio": "<Boolean>",
  "id": "<Base32-UUIDv4>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "audio": "<Boolean>",
  "video": "<Boolean>"
}

音声ストリーミング機能

audio-streaming.failed

音声ストリーミング URL への接続を諦めた際にウェブフックを送信します。

{
  "type": "audio-streaming.failed",
  "id": "<Base32-UUIDv4>",
  "timestamp": "<UTC RFC3339 Timestamp>",
  "label": "<String>",
  "version": "<String>",
  "node_name": "<String>",
  "log_written": "<Boolean>",
  "channel_id": "<String>",
  "session_id": "<Base32-UUIDv4>",
  "client_id": "<String | Base32-UUIDv4>",
  "bundle_id": "<String | Base32-UUIDv4>",
  "connection_id": "<Base32-UUIDv4>",
  "data": {
    "failed_reason": "<String>"
  },
  "role": "<sendrecv | sendonly | recvonly>",
  "multistream": "<Boolean>",
  "simulcast": "<Boolean>",
  "spotlight": "<Boolean>"
}

HTTP ヘッダー

警告

この機能は 実験的機能 のため、正式版では仕様が変更される可能性があります

注釈

JSON のパース時の判断などに利用してください。

sora-event-webhook-type

注意

x-sora-event-webhook-type は非推奨です、 sora-event-webhook-type を利用してください

イベントウェブフックの HTTP ヘッダー に sora-event-webhook-type と x-sora-event-webhook-type というヘッダー名でイベントウェブフックのタイプが入ってきます。

type が connection.created の場合は sora-event-webhook-type: connection.created と x-sora-event-webhook-type: connection.created のように値が入ってきます。

sora-session-id

イベントウェブフックの HTTP ヘッダー に sora-session-id というヘッダー名でセッション ID が入ってきます。

セッション ID が 46NNAV9S0X3TD778A1JBYYCBS8 の場合は sora-session-id: 46NNAV9S0X3TD778A1JBYYCBS8 のように値が入ってきます。

sora-connection-id

イベントウェブフックの HTTP ヘッダー に sora-connection-id というヘッダー名でコネクション ID が入ってきます。

コネクション ID が 7WSWCM0Z2H0614W5PJERR3F5WR の場合は sora-connection-id: 7WSWCM0Z2H0614W5PJERR3F5WR のように値が入ってきます。

シーケンス図

connection.*

        sequenceDiagram
    participant C as クライアント
    participant S as WebRTC SFU S
    participant A as アプリケーションサーバー
    note over C,A: 認証成功
    S->>C: "type": "offer"
    C->>S: "type": "answer"
    note over C,S: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created"
    A-->>-S: 200 OK
    note over C,S: 接続から 1 分経過
    S->>+A: イベントウェブフック<br/>"type": "connection.updated"
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed"
    A-->-S: 200 OK
    S->>C: WebSocket Close
    

event_metadata

        sequenceDiagram
    participant C as クライアント
    participant S as WebRTC SFU S
    participant A as アプリケーションサーバー
    C->>+S: "type": "connect"
    S->>+A: 認証ウェブフック
    A-->>-S: 200 OK<br>"allowed: true,<br>"event_metadata": {"pk": 1}
    S->>C: "type": "offer"
    C->>S: "type": "answer"
    note over C,S: WebRTC 確立
    S->>+A: イベントウェブフック<br/>"type": "connection.created",<br>"event_metadata": {"pk": 1}
    A-->>-S: 200 OK
    note over C,S: 接続から 1 分経過
    S->>+A: イベントウェブフック<br/>"type": "connection.updated",<br>"event_metadata": {"pk": 1}
    A-->>-S: 200 OK
    C->>S: "type": "disconnect"
    S->>+A: イベントウェブフック<br/>"type": "connection.destroyed",<br>"event_metadata": {"pk": 1}
    A-->-S: 200 OK
    S->>C: WebSocket Close
    

コンテンツ

• イベントウェブフック
  • 概要
  • 注意
  • ログ
    • event_webhook.jsonl
    • event_webhook_error.jsonl
  • 設定
    • event_webhook_url
    • connection_updated_webhook_interval
    • ignore_connection_updated_webhook
  • 接続イベント
    • 共通項目
    • connection.created
    • connection.destroyed
    • connection.updated
    • connection.failed
  • 録画・録音イベント
    • recording.started
    • recording.report
      • 一括録画時 recording.report
      • 分割録画時 recording.report
  • 録画・録音保存イベント
    • archive.started
    • archive.available
    • split-archive.available
    • split-archive.end
    • archive.failed
  • スポットライト機能
    • spotlight.focused
    • spotlight.unfocused
  • 音声ストリーミング機能
    • audio-streaming.failed
  • HTTP ヘッダー
    • sora-event-webhook-type
    • sora-session-id
    • sora-connection-id
  • シーケンス図
    • connection.*
    • event_metadata