イベントウェブフック

概要

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

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

注意

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

設定

ウェブフック通知先のサーバーがベーシック認証を利用している場合

もしウェブフック通知先のサーバーがベーシック認証を利用している場合は sora.conf にて webhook_basic_authntrue を設定することでベーシック認証を利用できます。

webhook_basic_authn_user_idwebhook_basic_authn_password に使用するユーザー ID とパスワードを設定して下さい。

ウェブフック通知先のサーバーが自己署名証明書などを利用している場合

この設定はおすすめしません

デフォルトでは自己署名証明書などの正規の認証局から発行されていない証明書を利用した場合には、信頼できないと判断しエラーになります。

もし自己署名証明書を利用したサーバーがウェブフックの通知先になる場合は、 sora.conf にて webhook_insecuretrue を設定することで証明書のチェックを行わないようになります。

event_webhook_url

デフォルト

未設定

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

この URL には HTTPS の URL を指定することも可能です。

HTTPS の URL を指定する場合は、通知先のアプリケーションには正規の認証局から発行された証明書を利用してください。

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

HTTP ヘッダー

注釈

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

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

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

接続イベント

  • connection.createdconnection.destroyed はセットです。

  • connection.created が通知されずに connection.destroyed が通知されることはありません。

  • connection.created が通知された場合、 connection.destroyed必ず 通知されます。

  • conneciton.created の後に connection.destroyed が通知されます。順番は保証されます。

共通項目

  • id

    • イベント毎の ID です

  • version

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

  • label

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

  • node_name

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

  • minutes

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

  • created_time

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

  • total_received_bytes

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

  • total_sent_bytes

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

  • turn_transport_type

    • udp か tcp が入ってきます

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

  • audio

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

    • コーデックやビットレートが入ってくる場合は {"codec_type": "OPUS", "bit_rate": 32} が入ってきます

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

    • ビットレートはクライアントが送ってこない場合は含まれません

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

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

  • video

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

    • コーデックやビットレートが入ってくる場合は {"codec_type": "VP9", "bit_rate": 100} が入ってきます

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

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

        • デフォルトは 500 です

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

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

  • multistream

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

  • simulcast

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

  • spotlight

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

  • role

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

  • event_metadata

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

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

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

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

  • channel_id

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

  • session_id

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

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

  • client_id

    • コネクションが提案してきたクライアント ID です

  • connection_id

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

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

connection.created

接続通知

シグナリングの接続が成功して、WebRTC としての通信が開始可能になった状態を通知します。

  • channel_connections

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

    • 自分は含まれません

  • channel_sendrecv_connections

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

    • 自分は含まれません

  • channel_sendonly_connections

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

    • 自分は含まれません

  • channel_recvonly_connections

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

    • 自分は含まれません

{
  "type": "connection.created",
  "channel_id": "sora",
  "sesison_id": "RH87Z6K7H135KE8BG5Z09TTBTM",
  "connection_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "timestamp": "2020-12-07T05:53:41.767758Z",
  "client_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "event_metadata": "<JSON>",
  "data": {
    "created_time": "<UNIX-Time>",
    "audio": {
      "codec_type": "OPUS"
    },
    "channel_connections": 1,
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 1,
    "channel_sendrecv_connections": 0,
    "created_time": 1628069176,
    "minutes": 0,
    "total_received_bytes": 0,
    "total_sent_bytes": 0,
    "turn_transport_type": "tcp",
    "video": {
      "bit_rate": 500,
      "codec_type": "VP9"
    }
  },
  "id": "QEE8PG3SE12618AZZYF9ND2DR4",
  "label": "WebRTC SFU Sora",
  "multistream": false,
  "node_name": "[email protected]",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "version": "2021.2"
}

connection.destroyed

切断通知

シグナリングの接続が切断したことを通知します。

  • reason

    • DisconnectChannel API または Disconnect API を利用して切断した際、オプションの reason に指定した JSON がこの reason に含まれます

    • 指定しなかった場合、またはそれ以外の場合は null が入ります

  • type_disconnect_reason

    • "type": "disconnect" 送信時に "reason" に指定した 文字列 が入ります

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

  • disconnect_api_reason

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

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

  • channel_connections

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

    • 自分は含まれません

  • channel_sendrecv_connections

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

    • 自分は含まれません

  • channel_sendonly_connections

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

    • 自分は含まれません

  • channel_recvonly_connections

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

    • 自分は含まれません

{
  "type": "connection.destroyed",
  "channel_id": "sora",
  "sesison_id": "RH87Z6K7H135KE8BG5Z09TTBTM",
  "connection_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "timestamp": "2020-12-07T05:55:10.097806Z",
  "client_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "event_metadata": "<JSON>",
  "data": {
    "created_time": "<UNIX-Time>",
    "audio": {
      "codec_type": "OPUS"
    },
    "channel_connections": 0,
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 0,
    "channel_sendrecv_connections": 0,
    "minutes": 1,
    "reason": null,
    "type_disconnect_reason": "NO-ERROR",
    "total_received_bytes": 6501144,
    "total_sent_bytes": 8482,
    "turn_transport_type": "tcp",
    "video": {
      "bit_rate": 500,
      "codec_type": "VP9"
    }
  },
  "id": "M9AF614GC97EZ3YNFWSBE2WN8R",
  "label": "WebRTC SFU Sora",
  "multistream": false,
  "node_name": "[email protected]",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "version": "2021.2"
}

connection.updated

接続状態更新通知

接続したタイミングから、クライアント毎の接続状態が、それぞれ 1 分間に 1 回送られてきます。

  • channel_connections

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

    • 自分が含まれます

  • channel_sendrecv_connections

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

    • 自分が含まれます

  • channel_sendonly_connections

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

    • 自分が含まれます

  • channel_recvonly_connections

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

    • 自分が含まれます

{
  "type": "connection.updated",
  "channel_id": "sora",
  "sesison_id": "RH87Z6K7H135KE8BG5Z09TTBTM",
  "connection_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "timestamp": "2020-12-07T05:54:41.766169Z",
  "client_id": "FW0CJSHETX0RXAGX8WWEXNBQN8",
  "event_metadata": "<JSON>",
  "data": {
    "audio": {
      "codec_type": "OPUS"
    },
    "channel_connections": 1,
    "channel_recvonly_connections": 0,
    "channel_sendonly_connections": 1,
    "channel_sendrecv_connections": 0,
    "created_time": 1628069176,
    "minutes": 1,
    "total_received_bytes": 4396378,
    "total_sent_bytes": 5686,
    "turn_transport_type": "tcp",
    "video": {
      "bit_rate": 500,
      "codec_type": "VP9"
    }
  },
  "id": "8PKRS4RAMX6H97ZZM33Q745TM8",
  "label": "WebRTC SFU Sora",
  "multistream": false,
  "node_name": "[email protected]",
  "role": "sendonly",
  "simulcast": false,
  "spotlight": false,
  "version": "2021.2"
}

connection.failed

失敗通知

重要

この通知を有効にする場合は、 sora.conf にて ignore_connection_failed_webhook を無効にする必要があります。

シグナリングが失敗したり、異常が起きたりした場合に通知されます。

{
    "type": "connection.failed",
    "id": "<Base32-UUIDv4>",
    "role": "<sendrecv | sendonly | recvonly>",
    "channel_id": "<String>",
    "client_id": "<String or 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>",
    "multistream": "<Boolean>",
    "node_name": "[email protected]",
    "simulcast": "<Boolean>",
    "spotlight": "<Boolean>",
    "version": "<String>"
}

録画・録音イベント

recording.report

録画報告通知

  • data.archives[].start_time_offset

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

  • data.archives[].stop_time_offset

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

  • data.metadata_filename

    • 2022 年 12 月リリースの Sora にて廃止されます

    • data.filename を利用してください

  • data.metadata_file_path

    • 2022 年 12 月リリースの Sora にて廃止されます

    • data.file_path を利用してください

  • data.metadata

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

{
    "type": "recording.report",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "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": "<Integer>",
        "file_path": "<String>",
        "filename": "<String>",
        "metadata_file_path": "<String>",
        "metadata_filename": "<String>",
        "archives": [
            {
                "client_id": "<String or Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "filename": "<String>",
                "file_path": "<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>"
            },
            {
                "client_id": "<String or Base32-UUIDv4>",
                "connection_id": "<Base32-UUIDv4>",
                "filename": "<String>",
                "file_path": "<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>"
            }
        ]
    }
}

録画・録音保存イベント

archive.available

録画保存したファイルが利用可能になった通知

  • start_timestamp

    • この録画が開始された時刻(UTC)を RFC3339 で表しています

  • stop_timestamp

    • この録画が終了した時刻(UTC)を RFC3339 で表しています

  • start_time

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

  • stop_time

    • この録画が終了した時刻を UNIX 秒で表しています

  • stats

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

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

{
    "type": "archive.available",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "event_metadata": "<JSON>",
    "data": {
        "channel_id": "<String>",
        "recording_id": "<Base32-UUIDv4>",
        "client_id": "<String or Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "created_at": "<Unix Time>",
        "filename": "<String>",
        "file_path": "<String>",
        "metadata_filename": "<String>",
        "metadata_file_path": "<String>",
        "size": "<Integer>",
        "audio": {
            "codec_type": "<String>"
        },
        "video": {
            "codec_type": "<String>",
            "bit_rate": "<Integer>",
            "height": "<Integer>",
            "width": "<Integer>"
        },
        "stats": {},
        "start_time": "<Unix Time>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_time": "<Unix Time>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
    }
}

archive.split

分割された録画ファイルが利用可能になった通知

  • split_index

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

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

  • start_time

    • 分割して出力された録画ファイルを開始した時間

  • stop_time

    • 分割して出力された録画ファイルを終了した時間

  • stats

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

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

{
    "type": "archive.split",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "data": {
        "channel_id": "<String>",
        "recording_id": "<Base32-UUIDv4>",
        "split_index": "0001",
        "client_id": "<String or Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "created_at": "<Unix Time>",
        "filename": "<String>",
        "file_path": "<String>",
        "metadata_filename": "<String>",
        "metadata_file_path": "<String>",
        "size": "<Integer>",
        "video": {
            "codec_type": "<String>",
            "bit_rate": "<Integer>",
            "height": "<Integer>",
            "width": "<Integer>"
        },
        "audio": {
            "codec_type": "<String>"
        },
        "stats": {},
        "start_time": "<Unix Time>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_time": "<Unix Time>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
    }
}

archive.end

  • start_time

    • 録画を開始した時間

  • stop_time

    • 録画を終了した時間

  • stats

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

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

{
    "type": "archive.end",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "data": {
        "channel_id": "<String>",
        "recording_id": "<Base32-UUIDv4>",
        "client_id": "<String or Base32-UUIDv4>",
        "connection_id": "<Base32-UUIDv4>",
        "video": {
            "codec_type": "<String>",
            "bit_rate": "<Integer>",
            "height": "<Integer>",
            "width": "<Integer>"
        },
        "audio": {
            "codec_type": "<String>",
            "bit_rate": "<Integer>"
        },
        "stats": {},
        "start_time": "<Unix Time>",
        "start_timestamp": "<UTC RFC3339 Timestamp>",
        "stop_time": "<Unix Time>",
        "stop_timestamp": "<UTC RFC3339 Timestamp>",
    }
}

archive.failed

録画ファイル保存失敗通知

{
    "type": "archive.failed",
    "id": "<Base32-UUIDv4>",
    "version": "<String>",
    "label": "<String>",
    "node_name": "<String>",
    "timestamp": "<UTC RFC3339 Timestamp>",
    "channel_id": "<String>",
    "client_id": "<String or Base32-UUIDv4>",
    "connection_id": "<Base32-UUIDv4>",
    "data": {
        "recording_id": "<Base32-UUIDv4>",
        "filename": "<String>",
        "file_path": "<String>",
        "video": {
            "codec_type": "<String>",
            "bit_rate": "<Integer>",
            "height": "<Integer>",
            "width": "<Integer>"
        },
        "audio": {
            "codec_type": "<String>"
        },
        "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": "sora",
  "connection_id": "N5D19GJQX55PXC7VX31A05MZKC",
  "timestamp": "2020-12-08T06:21:04.130449Z",
  "audio": true,
  "client_id": "N5D19GJQX55PXC7VX31A05MZKC",
  "fixed": false,
  "id": "J35J78WGXS4NX77MYQWTEWEGNM",
  "label": "WebRTC SFU Sora",
  "version": "2021.2",
  "video": true
}

spotlight.unfocused

フォーカス解除通知

フォーカスが外れた際にウェブフックが飛びます。

{
  "type": "spotlight.unfocused",
  "channel_id": "sora",
  "connection_id": "8JTV2Q53WS56Z3K19HDAV4QN1C",
  "timestamp": "2020-12-08T06:21:04.142833Z",
  "audio": true,
  "client_id": "8JTV2Q53WS56Z3K19HDAV4QN1C",
  "id": "VSXG27VYZH7VXDQKB2XNW1HZN0",
  "label": "WebRTC SFU Sora",
  "version": "2021.2",
  "video": true
}

シーケンス図

connection.*

blockdiag クライアント Sora アプリケーション サーバー "type": "offer" "type": "answer" イベントウェブフック "type": "connection.created" 200 OK イベントウェブフック "type": "connection.updated" 200 OK "type": "disconnect" イベントウェブフック "type": "connection.destroye d" 200 OK WebSocket Close 認証成功 WebRTC 確立 接続から 1 分経過

event_metadata

blockdiag クライアント Sora アプリケーション サーバー "type": "connect" 認証ウェブフック 200 OK "allowed": true, "event_metadata": {"pk": 1} "type": "offer" "type": "answer" イベントウェブフック "type": "connection.created" , "event_metadata": {"pk": 1} 200 OK イベントウェブフック "type": "connection.updated" , "event_metadata": {"pk": 1} 200 OK "type": "disconnect" イベントウェブフック "type": "connection.destroye d", "event_metadata": {"pk": 1} 200 OK WebSocket Close WebRTC 確立 接続から 1 分経過
© Copyright 2021, Shiguredo Inc Created using Sphinx 4.4.0