# ウェブフック

## 概要

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

## ウェブフックリクエスト

- ウェブフックは HTTP/1.1 で送信します
- `content-type` は `application/json` です

## ウェブフックの設定

- ウェブフック URL を設定しない場合は、ウェブフックリクエストを送信しません
- ウェブフックログを出力しないという設定はありません

### 認証ウェブフック

**設定**: `auth_webhook_url` に認証ウェブフックの URL を指定します。
**ログ**: `auth_webhook.jsonl` に認証ウェブフックのログが出力されます

詳細は [認証ウェブフック](AUTH_WEBHOOK.html) をご確認ください。

### セッションウェブフック

**設定**: `session_webhook_url` にセッションウェブフックの URL を指定します。
**ログ**: `session_webhook.jsonl` に認証ウェブフックのログが出力されます

詳細は [セッションウェブフック](SESSION_WEBHOOK.html) をご確認ください。

### イベントウェブフック

**イベント**: `event_webhook_url` にイベントウェブフックの URL を指定します。
**ログ**: `event_webhook.jsonl` に認証ウェブフックのログが出力されます

詳細は [イベントウェブフック](EVENT_WEBHOOK.html) をご確認ください。


## ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する 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](SORA_CONF.html#7036dc) に指定することができます。

音声ストリーミングや統計エクスポーターでも CA 証明書を指定することができます。

- [audio_streaming_tls_verify_cacert_file](SORA_CONF.html#feef99)
- [stats_exporter_tls_verify_cacert_file](SORA_CONF.html#bcd961)

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

もしウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合は、
`sora.conf` にて [webhook_basic_authn](SORA_CONF.html#081a9f) を `true` に設定することでベーシック認証を利用できます。

[webhook_basic_authn_user_id](SORA_CONF.html#a107fd) と [webhook_basic_authn_password](SORA_CONF.html#f70fe9) に利用するユーザー ID とパスワードを設定して下さい。


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

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

この場合は `sora.conf` にて [webhook_tls_verify_cacert_file](SORA_CONF.html#7036dc) を指定することで、
指定されたルート CA を利用してサーバー証明書の検証を行います。

もしくは推奨はできませんが `sora.conf` にて、
[webhook_insecure](SORA_CONF.html#676769) を `true` に設定することで証明書のチェックを行わなくなります。

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

mTLS を利用する場合は `sora.conf` にて [webhook_tls_fullchain_file](SORA_CONF.html#93f2b9) にクライアント証明書、
[webhook_tls_privkey_file](SORA_CONF.html#7065d6) にクライアント秘密鍵を指定します。
送信先のサーバーが自己証明書などを利用している場合は [webhook_tls_verify_cacert_file](SORA_CONF.html#7036dc) にサーバー CA 証明書を指定します。

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

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

## `connection.updated` と `session.updated` ウェブフック

[session.updated](SESSION_WEBHOOK.html#2a5b1b) と [connection.updated](EVENT_WEBHOOK.html#5430cd) は一定間隔で送信してくるウェブフックです。

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

## ウェブフックの順番保証

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 レコードが存在しない