轉真人 Webhook 事件

對話轉真人指派完成時，MaiAgent 以 Webhook 將 handoff.created 事件推送到你指定的系統端點，本篇說明事件格式、簽章驗證與重試行為

當客服入口（收件匣）完成「轉真人」指派時，MaiAgent 會以 HTTPS POST 將一筆 handoff.created 事件推送到你設定的端點，讓派工、告警或 CRM 系統自動接手，不需輪詢。

啟用方式

由客戶的管理者或串接人員在後台自助完成，毋需工程協助：

1. 後台 → 設定 → 收件匣 → 選擇收件匣 → 「轉真人」頁籤 → 「通知」分頁

2. 開啟「Webhook 通知（系統串接）」開關，填入接收端網址（僅接受 https:// 開頭）

3. （選填但建議）填入簽章密鑰，啟用來源驗證（見下方「簽章驗證」）

Webhook 與通知中心、Email 是三個獨立開關，互不影響；預設關閉、逐收件匣啟用。此通道與收件匣既有的「訊息 Webhook」（訊息收送）互不相干。

事件格式

POST <你設定的網址>
Content-Type: application/json

{
  "event": "handoff.created",
  "conversationId": "6c2b7c1e-...",
  "inboxId": "0f9a3d42-...",
  "organizationId": "b1d20c77-...",
  "assigneeId": "3e8f5a90-...",
  "contactId": "a4c1f6b3-...",
  "conversationUrl": "https://admin.maiagent.ai/..."
}

欄位	類型	說明
event	string	固定為 handoff.created
conversationId	string (uuid)	對話識別碼
inboxId	string (uuid)	收件匣識別碼
organizationId	string (uuid)	組織識別碼
assigneeId	string (uuid) | null	被指派客服的成員識別碼
contactId	string (uuid) | null	客戶（聯絡人）識別碼
conversationUrl	string (uri)	後台對話頁連結

Payload 只含識別資訊與後台連結，不含對話文字內容；需要對話內容時，請以識別碼呼叫對話與訊息 API 查詢。

簽章驗證（建議啟用）

在後台設定簽章密鑰後，每次推送會帶下列標頭：

X-MaiAgent-Signature-256: sha256=<hex digest>

值為以密鑰對 原始 request body bytes 計算的 HMAC-SHA256 十六進位摘要。驗證時務必使用收到的原始 bytes，不要先解析再重新序列化（欄位順序與空白差異會使摘要不一致）。

import hashlib
import hmac


def verify_signature(raw_body: bytes, header_value: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header_value)

密鑰為 write-only：儲存後不回顯，後台僅顯示「已設定」；欄位留空儲存代表維持既有密鑰，更換直接輸入新值，移除請使用「清除密鑰」操作。未設定密鑰時，推送不帶簽章標頭。

回應與重試

• 接收端應在 10 秒內以 2xx 狀態碼回應，回應內容不拘。

• 逾時、連線失敗或非 2xx 回應時，系統會自動重試，最多 3 次、間隔 60 秒；重試送出的內容與原始推送完全相同，接收端請自行冪等處理（例如以 conversationId 去重）。

• Webhook 推送失敗不影響轉真人主流程，也不影響通知中心與 Email 通知。