> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pathors.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 初始設定

> 在 agent 設定 webhook URL，選擇要由哪些 lifecycle 事件觸發。

當 agent 設定了 `postSessionWebhook`，Pathors 會在每個你訂閱的 lifecycle 事件觸發時 POST JSON 到你指定的 URL。可複選要訂閱哪些事件，每個事件帶各自的 payload，由 body 最頂層的 `event` 欄位區分。

## 事件種類

| 事件                  | 觸發時機                  | 備註                                                                                                                                   |
| ------------------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `session.ended`     | 對話結束時。                | 為了向下相容，這是 default。對 call session，通話的最終狀態跟時長此時可能還沒就緒。                                                                                 |
| `call.ended`        | 通話結束時。                | Call session 限定。Text session 不會收到這個事件。                                                                                               |
| `recording.ready`   | 通話錄音處理完成時（成功或失敗）。     | Call session 限定。會 gate `session.finalized` —— finalization 會等錄音處理完成（有 timeout backstop）。成功時帶短期有效的 `recordingUrl`；也是唯一會回報錄音**失敗**的事件。 |
| `session.finalized` | 這個 session 的所有事情都做完時。 | 一定是該 session 的**最後**一個事件。把所有其他事件的資料合併成一份，包含對話逐字稿（`messages`），有錄音的通話還帶 `recordingUrl`。                                                |

## 設定

Webhook 設定在 agent 上。在 agent 設定 UI 操作，或透過 [update-agent](/zh-Hant/api-reference/v1/agent/update-agent) 程式化設定：

```bash theme={null}
curl -X PATCH https://api.pathors.com/v1/projects/{projectId}/agent \
  -H 'Authorization: Bearer <your-api-key>' \
  -H 'Content-Type: application/json' \
  -d '{
    "postSessionWebhook": {
      "url": "https://your-server.example.com/pathors-webhook",
      "events": ["session.ended", "session.finalized"]
    }
  }'
```

<ParamField body="url" type="string" required>
  接收 POST + JSON 的 HTTPS endpoint。
</ParamField>

<ParamField body="headers" type="array">
  選填。送到你的 endpoint 的 custom HTTP headers，連同 `Content-Type: application/json`。每筆格式為 `{ "key": string, "value": string }`。用途由你決定 —— 例如帶 `Authorization` token 驗證來源，或在共用 receiver 上加路由識別碼等。
</ParamField>

<ParamField body="events" type="array of string">
  哪些 lifecycle 事件會觸發 webhook。省略時 default `["session.ended"]`，保留 2026 年前的單一事件行為。
</ParamField>

## 訂閱多個事件

訂多個事件代表每個 session 每個訂閱事件會收到一筆 POST。用最頂層 `event` 欄位分流 —— 範例見 [payloads 頁面的實作範例](/zh-Hant/api-reference/webhook/payloads#implementation-example)。

```json theme={null}
{
  "events": ["session.ended", "call.ended", "session.finalized"]
}
```

## Delivery 語意

* **`session.finalized` 每個 session 最多觸發一次。** Pathors 在底層 DB row 上做 CAS guard，即使並發寫入也只去重發一次。其他事件（`session.ended`、`call.ended`、`recording.ready`）是按各處理步驟發出的，可能會被重送（例如內部 retry）；需要 exactly-once 時請以 `(sessionId, event)` 去重。
* **不會自動 retry。** Endpoint 回非 2xx 時會記到 `webhook_logs`，但 Pathors 不重送。需要 at-least-once 自己接到 durable queue 後再消費。
* **儘快回 response。** Pathors 會同步等待你的 response，長時間處理請放在你那邊的背景 job。
* **向下相容。** 2026 之前建立的 `postSessionWebhook` 沒有 `events` 欄位，行為等同 `events: ["session.ended"]`。**現有 receiver 不需任何改動**。

## 下一步

<CardGroup cols={2}>
  <Card title="Webhook payloads" icon="code" href="/zh-Hant/api-reference/webhook/payloads">
    完整 payload schema 跟 receiver 範例。
  </Card>

  <Card title="Update agent" icon="pen" href="/zh-Hant/api-reference/v1/agent/update-agent">
    透過 API 設定 `postSessionWebhook`。
  </Card>
</CardGroup>