Webhooks

當潛在客戶、表單、對話或升級處理發生變化時，Webhook 會傳送已簽署的通知。此功能需要 Hobby 方案或以上，且帳單狀態為有效。

設定端點

開啟代理程式的設定 → Webhooks，選擇一或多個事件，輸入公開的 HTTPS 端點，然後建立訂閱。Agentkit 會為同一個端點下的所有事件列保留同一組簽署密鑰。帳戶擁有者可以從端點卡片中顯示或輪替此密鑰。

支援的事件名稱如下：

• lead_created
• form_submission（舊版潛在客戶別名）
• custom_form_submitted
• conversation_started
• conversation_ended
• escalation_created

conversation_ended 會在 30 分鐘沒有新訊息後觸發。其逐字稿是最多 200 則訊息的不可變快照，每則訊息上限為 2,000 個字元。僅在 Playground 中進行、且沒有使用者訊息的對話不會派送此事件。逐字稿分析目前為 null。

事件封套

每個事件都使用相同且穩定的封套結構：

{
  "event": "conversation_started",
  "eventId": "evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a",
  "timestamp": "2026-07-14T13:05:02.000Z",
  "data": {
    "conversationId": "0b8e43d2-6cdf-42a8-8df1-a17f082df99f",
    "conversationReferenceId": "a1b2c3d4e5f6a7b8",
    "chatbotId": "d21c2aca-52d7-4056-a7d6-805713d3d39c",
    "source": "widget",
    "startedAt": "2026-07-14T13:05:02.000Z"
  }
}

請將 eventId 作為你的冪等性金鑰使用。傳送方式為至少送達一次，且不保證順序。重試時會重複使用相同的事件 ID、發生時間戳記與 JSON 位元組內容。

驗證簽章

每次傳送都包含：

X-Agentkit-Event: conversation_started
X-Agentkit-Event-Id: evt_91d0a3ce-5a9d-4b67-a454-bafb9484281a
X-Agentkit-Signature: t=1784043902,v1=<hex-hmac-sha256>

請將請求本文讀取為原始的 UTF-8 文字。解析 t 與 v1，並使用端點密鑰對 t + "." + rawBody 的確切位元組內容計算 HMAC-SHA256，再以常數時間函式比對雜湊值。請勿在驗證前先解析並重新序列化 JSON。請依你的重放防護政策拒絕過期的時間戳記。

import { createHmac, timingSafeEqual } from 'node:crypto';

const expected = createHmac('sha256', process.env.AGENTKIT_WEBHOOK_SECRET!)
  .update(`${timestamp}.${rawBody}`, 'utf8')
  .digest('hex');

const valid = timingSafeEqual(Buffer.from(expected, 'hex'), Buffer.from(v1, 'hex'));

可靠性與傳送結果

請在 10 秒內回傳 2xx 狀態碼。非 2xx 回應、逾時或網路錯誤，會在初次請求後以 QStash 退避機制重試五次（通常總共六次嘗試）。設定頁面會顯示最近 20 筆最終結果。

一個已耗盡重試次數的事件只會讓連續失敗次數加一次，無論嘗試次數或重複回呼為何。訂閱只有在至少連續 10 個事件耗盡重試次數、且時間跨度至少七天時，才會自動停用。擁有者會收到一則可重試的通知，並可在修復後重新啟用。成功送達的事件會重設連續失敗次數。

端點 URL 必須使用 HTTP 或 HTTPS、必須是公開位址，且不得指向 localhost、私有／連結本地（link-local）IP 範圍，或雲端中繼資料端點。正式環境則必須使用 HTTPS。投遞時，Agentkit 只會解析一次主機名稱、要求所有解析出的位址都必須是公開位址，並將連線固定於這些位址，因此 DNS rebinding 無法把投遞導向內部位址。

排程啟用

閒置對話掃描的程式碼預設為停用狀態。維運人員可在部署後審核並執行 pnpm --filter chatbots setup:idle-conversation-webhooks。此指令會建立 15 分鐘一次的 QStash 排程；合併程式碼本身並不會建立或啟用該排程。

後續步驟

• Webhooks API
• Zapier 整合