ウェブフック¶
概要¶
Sora では認証の判断や状態の通知などを全てウェブフックを利用します。 認証ウェブフックやセッションウェブフックの一部では、ウェブフックの戻り値で設定を払い出すことができます。
ウェブフックリクエスト¶
ウェブフックは HTTP/1.1 で送信します
content-type
はapplication/json
です
ウェブフックの設定¶
ウェブフック URL を設定しない場合は、ウェブフックリクエストを送信しません
ウェブフックログを出力しないという設定はありません
認証ウェブフック¶
- 設定:
auth_webhook_url
に認証ウェブフックの URL を指定します。- ログ:
auth_webhook.jsonl
に認証ウェブフックのログが出力されます
詳細は 認証ウェブフック をご確認ください。
セッションウェブフック¶
- 設定:
session_webhook_url
にセッションウェブフックの URL を指定します。- ログ:
session_webhook.jsonl
に認証ウェブフックのログが出力されます
詳細は セッションウェブフック をご確認ください。
イベントウェブフック¶
- イベント:
event_webhook_url
にイベントウェブフックの URL を指定します。- ログ:
event_webhook.jsonl
に認証ウェブフックのログが出力されます
詳細は イベントウェブフック をご確認ください。
ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する 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.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-INTERNAL-ERROR
EVENT-WEBHOOK-ERROR
reason¶
reason に nxdomain が含まれる場合
DNS A レコードまたは AAAA レコードが存在しない