# ウェブフック

## 概要

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

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

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

## ウェブフックレスポンス

- ウェブフックのレスポンスは HTTP/1.1 で返却します
- レスポンスの `content-type` は `application/json` です
- レスポンスのステータスコードは `200 OK` 等の 200 番台のステータスコードである必要があります

## ウェブフックの設定

- ウェブフック URL を設定しない場合は、ウェブフックリクエストを送信しません
- 認証ウェブフックログと統計ウェブフックログは出力しない設定にできます

### 認証ウェブフック

**設定**: `auth_webhook_url` に認証ウェブフックの URL を指定します。
**正常ログ**: `auth_webhook.jsonl` に認証ウェブフックが **正常に動作したログ** が出力されます
**エラーログ**: `auth_webhook_error.jsonl` に認証ウェブフックがエラーになったログが出力されます

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

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

**設定**: `session_webhook_url` にセッションウェブフックの URL を指定します。
**正常ログ**: `session_webhook.jsonl` にセッションウェブフックが **正常に動作したログ** が出力されます
**エラーログ**: `session_webhook_error.jsonl` にセッションウェブフックがエラーになったログが出力されます

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

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

**設定**: `event_webhook_url` にイベントウェブフックの URL を指定します。
**全てのログ**: `event_webhook.jsonl` にイベントウェブフックの **全てのログ** が出力されます
**エラーログ**: `event_webhook_error.jsonl` にイベントウェブフックでエラーになったログが出力されます

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

### 統計ウェブフック

**設定**: `stats_webhook_url` に統計ウェブフックの URL を指定します。
**全てのログ**: `stats_webhook.jsonl` に統計ウェブフックの **全てのログ** が出力されます
**エラーログ**: `stats_webhook_error.jsonl` に統計ウェブフックでエラーになったログが出力されます

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

## ウェブフックのタイムアウト時間の指定

### コネクション確立のタイムアウト時間の指定

Sora がウェブフックを送信する際に、ウェブフック送信先のサーバーとのコネクションを確立する際のタイムアウト時間を指定できます。

デフォルトでは 30 秒です。

`sora.conf` の [webhook_connect_timeout](SORA_CONF.html#7a0122) を設定してください。

### レスポンスのタイムアウト時間の指定

Sora がウェブフックを送信し、そのレスポンスを受け取るまでのタイムアウト時間を指定できます。

デフォルトでは 5 秒です。

`sora.conf` の [webhook_response_timeout](SORA_CONF.html#e81d13) を設定してください。


## ウェブフックリクエストなどの送信先サーバー証明書の検証に利用する 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)


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

もしウェブフックリクエスト送信先のサーバーがベーシック認証を利用している場合は、
`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 にて自己署名証明書 (Self-signed certificate) を利用する場合、
`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](SORA_CONF.html#6c895b) を `true` にすることで、
IPv6 のみのサーバーに対して、ウェブフックリクエストを送信できるようになります。

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

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

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

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

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

- [connection.created](EVENT_WEBHOOK.html#eef06c) の前に [connection.destroyed](EVENT_WEBHOOK.html#6c02d0) が送信されることはありません
- [archive.started](EVENT_WEBHOOK.html#462c97) の前に [archive.available](EVENT_WEBHOOK.html#de9132) や [split-archive.available](EVENT_WEBHOOK.html#555071) や [split-archive.end](EVENT_WEBHOOK.html#31be7a) が送信されることはありません

## ウェブフックの警告メッセージ

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

- AUTH-WEBHOOK-INTERNAL-ERROR
- SESSION-WEBHOOK-ERROR
- EVENT-WEBHOOK-ERROR
- STATS-WEBHOOK-ERROR

### reason

- reason に `nxdomain` が含まれる場合- DNS A レコードまたは AAAA レコードが存在しない
- reason に `timeout` が含まれる場合- ウェブフック送信先のサーバーとの接続確立が [webhook_connect_timeout](SORA_CONF.html#7a0122) で設定した時間を超えた
  - ウェブフック送信先のサーバーからのレスポンスが [webhook_response_timeout](SORA_CONF.html#e81d13) で設定した時間を超えた
- reason に `closed` が含まれる場合- ウェブフック送信先の TCP 接続が意図しないタイミングで切断された
  - この問題が発生した場合はウェブフックは失敗と判断します
- reason に `enotconn` が含まれる場合- ウェブフック送信先の TCP 接続が意図しないタイミングで切断された際、何かしらの処理を行った
  - この問題が発生した場合はウェブフックは失敗と判断します