ウェブフック

概要

Sora では認証の判断や状態の通知などを全てウェブフックを利用します。 認証ウェブフックやセッションウェブフックの一部では、ウェブフックの戻り値で設定を払い出すことができます。

ウェブフックリクエスト

  • ウェブフックは HTTP/1.1 で送信します

  • content-typeapplication/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_authntrue に設定することでベーシック認証を利用できます。

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

ウェブフックリクエスト送信先のサーバーが自己署名証明書などを利用している場合

Sora は sora.conf にて CA 証明書を指定しない限り OS に組み込まれた信頼された CA 証明書を利用します。 そのため、自己署名証明書などの正規の認証局から発行されていない証明書を使用した場合には、信頼できないと判断しエラーになります。

この場合は sora.conf にて webhook_tls_verify_cacert_file を指定することで、 指定されたルート CA を利用してサーバー証明書の検証を行います。

もしくは推奨はできませんが sora.conf にて、 webhook_insecuretrue に設定することで証明書のチェックを行わなくなります。

ウェブフックリクエスト送信先のサーバーが mTLS を利用している場合

mTLS を利用する場合は sora.conf にて webhook_tls_fullchain_file にクライアント証明書、 webhook_tls_privkey_file にクライアント秘密鍵を指定します。 送信先のサーバーが自己証明書などを利用している場合は webhook_tls_verify_cacert_file にサーバー CA 証明書を指定します。

ウェブフックリクエスト送信先が IPv6 アドレスのみ対応している場合

Sora は sora.conf にて webhook_ipv6true にすることで、 IPv6 のみのサーバーに対して、ウェブフックリクエストを送信できるようになります。

connection.updatedsession.updated ウェブフック

session.updatedconnection.updated は一定間隔で送信してくるウェブフックです。

これらのウェブフックをアプリケーションサーバー側で記録しておくことで、 もし何か障害が発生しウェブフックが通知されなくなった場合でも、 そのコネクションが存在するかどうかの判断を行う事ができるようになります。

ウェブフックの順番保証

Sora は一部のイベントウェブフックリクエストを送信する際、順番を保証して送信します。

  • connection.created の前に connection.destroyed が送信されることはありません

  • archive.started の前に archive.availablesplit-archive.availablesplit-archive.end が送信されることはありません

ウェブフックエラーメッセージ

これらのエラーメッセージは sora.jsonl に出力されます。

  • AUTH-WEBHOOK-INTERNAL-ERROR

  • SESSION-WEBHOOK-INTERNAL-ERROR

  • EVENT-WEBHOOK-ERROR

reason

  • reason に nxdomain が含まれる場合

    • DNS A レコードまたは AAAA レコードが存在しない

© Copyright 2024, Shiguredo Inc Created using Sphinx 7.2.6