ウェブフック¶
概要¶
Sora では認証の判断や状態の通知などを全てウェブフックを利用します。 認証ウェブフックやセッションウェブフックの一部では、ウェブフックの戻り値で設定を払い出すことができます。
ウェブフックリクエスト¶
ウェブフックは HTTP/1.1 で送信します
content-typeはapplication/jsonです
ウェブフックの設定¶
ウェブフック URL を設定しない場合は、ウェブフックリクエストを送信しません
ウェブフックログを出力しない設定は認証ウェブフックログと統計ウェブフックログができます
認証ウェブフック¶
- 設定:
auth_webhook_urlに認証ウェブフックの URL を指定します。- 正常ログ:
auth_webhook.jsonlに認証ウェブフックが 正常に動作したログ が出力されます- エラーログ:
auth_webhook_error.jsonlに認証ウェブフックがエラーになったログが出力されます
詳細は 認証ウェブフック をご確認ください。
セッションウェブフック¶
- 設定:
session_webhook_urlにセッションウェブフックの URL を指定します。- 正常ログ:
session_webhook.jsonlにセッションウェブフックが 正常に動作したログ が出力されます- エラーログ:
session_webhook_error.jsonlにセッションウェブフックがエラーになったログが出力されます
詳細は セッションウェブフック をご確認ください。
イベントウェブフック¶
- イベント:
event_webhook_urlにイベントウェブフックの URL を指定します。- 全てのログ:
event_webhook.jsonlにイベントウェブフックの 全てのログ が出力されます- エラーログ:
event_webhook_error.jsonlにイベントウェブフックでエラーになったログが出力されます
詳細は イベントウェブフック をご確認ください。
統計ウェブフック¶
- イベント:
stats_webhook_urlにイベントウェブフックの URL を指定します。- 全てのログ:
stats_webhook.jsonlに統計ウェブフックの 全てのログ が出力されます- エラーログ:
stats_webhook_error.jsonlに統計ウェブフックでエラーになったログが出力されます
詳細は 統計ウェブフック をご確認ください。
ウェブフックのタイムアウト時間の指定¶
コネクション確立のタイムアウト時間の指定¶
Sora がウェブフックを送信する際に、ウェブフック送信先のサーバーとのコネクションを確立する際のタイムアウト時間を指定できます。
デフォルトでは 30 秒です。
sora.conf の webhook_connect_timeout を設定してください。
レスポンスのタイムアウト時間の指定¶
Sora がウェブフックを送信し、そのレスポンスを受け取るまでのタイムアウト時間を指定できます。
デフォルトでは 5 秒です。
sora.conf の webhook_response_timeout を設定してください。
ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する OS 組み込みのルート CA 証明書について¶
Sora は外部サーバーに HTTPS で通信を行う際、デフォルトでは OS に組み込まれた信頼された CA 証明書を利用します。
Ubuntu は
apt install ca-certificatesでインストールされる証明書を利用しますRHEL (または CentOS) は
dnf install ca-certificatesでインストールされる証明書を利用します
それぞれの OS の CA 証明書のパス以下になります。
Ubuntu は
/etc/ssl/certs/ca-certificates.crtのパスにある信頼された CA 証明書を利用しますRHEL (または CentOS) は
/etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pemのパスにある信頼された CA 証明書を利用します
OS の証明書の読み込みに失敗した場合は、サーバーから送られてくる証明書の検証を行わないようになり、接続毎に warning ログが出力されます。
ウェブフックで利用する CA 証明書は webhook_tls_verify_cacert_file に指定することができます。
音声ストリーミングや統計エクスポーターでも CA 証明書を指定することができます。
ウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合¶
もしウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合は、
sora.conf にて webhook_basic_authn を true に設定することでベーシック認証を利用できます。
webhook_basic_authn_user_id と webhook_basic_authn_password に利用するユーザー ID とパスワードを設定して下さい。
ウェブフックリクエスト送信先のサーバーが自己発行証明書などを利用している場合¶
Sora は sora.conf にて CA 証明書を指定しない限り OS に組み込まれた信頼された CA 証明書を利用します。
そのため、自己発行証明書などの正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。
この場合は sora.conf にて webhook_tls_verify_cacert_file を指定することで、
指定されたルート CA を利用してサーバー証明書の検証を行います。
Sora にて自己署名証明書(Self-signed certificate)を利用する場合、
sora.conf にて、 webhook_insecure を true に設定する必要があります。
ウェブフックリクエスト送信先のサーバーが mTLS を利用している場合¶
mTLS を利用する場合は sora.conf にて webhook_tls_fullchain_file にクライアント証明書、
webhook_tls_privkey_file にクライアント秘密鍵を指定します。
送信先のサーバーが自己証明書などを利用している場合は webhook_tls_verify_cacert_file にサーバー CA 証明書を指定します。
ウェブフックリクエスト送信先が IPv6 アドレスのみ対応している場合¶
Sora は sora.conf にて webhook_ipv6 を true にすることで、
IPv6 のみのサーバーに対して、ウェブフックリクエストを送信できるようになります。
connection.updated と session.updated ウェブフック¶
session.updated と connection.updated は一定間隔で送信してくるウェブフックです。
これらのウェブフックをアプリケーションサーバー側で記録しておくことで、 もし何か障害が発生しウェブフックが通知されなくなった場合でも、 そのコネクションが存在するかどうかの判断を行う事ができるようになります。
ウェブフックの順番保証¶
Sora は一部のイベントウェブフックリクエストを送信する際、順番を保証して送信します。
connection.created の前に connection.destroyed が送信されることはありません
archive.started の前に archive.available や split-archive.available や split-archive.end が送信されることはありません
ウェブフックの警告メッセージ¶
これらの警告メッセージは sora.jsonl に出力されます。
AUTH-WEBHOOK-INTERNAL-ERROR
SESSION-WEBHOOK-ERROR
EVENT-WEBHOOK-ERROR
STATS-WEBHOOK-ERROR
reason¶
reason に nxdomain が含まれる場合
DNS A レコードまたは AAAA レコードが存在しない