ウェブフック¶
概要¶
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 レコードが存在しない