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

​
事件種類

事件觸發時機備註
session.ended對話結束時。為了向下相容，這是 default。對 call session，通話的最終狀態跟時長此時可能還沒就緒。
call.ended通話結束時。Call session 限定。Text session 不會收到這個事件。
session.finalized這個 session 的所有事情都做完時。把所有其他事件的資料合併成一份。
recording.ready通話錄音處理完成時（成功或失敗）。Call session 限定。與 session.finalized 獨立 —— 可能在它之前或之後到。成功時帶短期有效的 recordingUrl。

​
設定

Webhook 設定在 agent 上。在 agent 設定 UI 操作，或透過 update-agent 程式化設定： 
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"]
    }
  }'
​
url
string
必填
接收 POST + JSON 的 HTTPS endpoint。
​
headers
array
選填。送到你的 endpoint 的 custom HTTP headers，連同 Content-Type: application/json。每筆格式為 { "key": string, "value": string }。用途由你決定 —— 例如帶 Authorization token 驗證來源，或在共用 receiver 上加路由識別碼等。
​
events
array of string
哪些 lifecycle 事件會觸發 webhook。省略時 default ["session.ended"]，保留 2026 年前的單一事件行為。

​
訂閱多個事件

訂多個事件代表每個 session 每個訂閱事件會收到一筆 POST。用最頂層 event 欄位分流 —— 範例見 payloads 頁面的實作範例。 
{
  "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 不需任何改動。

​
下一步

Webhook payloads

完整 payload schema 跟 receiver 範例。

Update agent

透過 API 設定 postSessionWebhook。