Skip to main content
當通話期間發生事件時,ThunderPhone 會向你的伺服器傳送 HTTP POST 請求——例如開始接聽來電、通話結束、評分作業完成、觸發警示等。提供 兩種傳送模式

Webhook 端點(建議使用)

支援多個 URL、各端點專屬密鑰、各端點事件篩選,以及自動重試。 透過 GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints 管理。

單一 URL 舊版 webhook

每個組織一個 URL。承載通話生命週期事件,包括 阻塞式 組態交換。 透過 GET/PUT /v1/webhook 管理。
event 目錄中的全部十種事件類型都會透過 webhook 端點傳送。六種通話生命週期事件 (telephony.incomingtelephony.completetelephony.toolweb.incomingweb.completeweb.tool)也會傳送至 舊版單一 URL webhook——如果你同時設定舊版 URL 與相符的端點,將在 兩個 路徑上都收到該事件。阻塞行為(telephony.incoming / web.incoming 組態 交換與 webhook 模式的 工具分派)僅存在於舊版路徑;每次端點傳送都是即發即棄的通知。

承載資料格式

端點傳送的內容是包含 dataevent_idtype 的 JSON 物件:
event_id 對每個發出的事件皆為唯一值。它在重試期間 以及 接收該事件的每個端點之間都完全相同——請依此去除重複事件。 舊版單一 URL webhook 會傳送相同的 typedata,但 不包含 event_id
在傳輸時,每個內容主體都會以標準格式序列化——鍵會依字母順序排列、 不含空白字元,並使用 UTF-8。本文文件中經過美化排版的範例 僅為了便於閱讀。 請參閱事件目錄,查看完整的事件 類型與承載資料欄位清單。

簽章驗證

每個請求都會在 X-ThunderPhone-Signature 標頭中,帶有針對原始請求本文的 HMAC-SHA256 簽章。簽署金鑰為端點的 secret(若為舊版傳遞,則使用組織層級 webhook 的 secret)。

步驟

  1. 在進行任何剖析之前讀取原始請求本文。
  2. 計算 hmac_sha256(secret, body).hexdigest()
  3. 以固定時間方式與 X-ThunderPhone-Signature 標頭比較。
我們簽署的正是傳送的位元組,而這些位元組是標準 JSON 序列化格式(排序的鍵、精簡分隔符號)。因此,針對原始本文驗證一定可行——若你的框架只提供已剖析的 JSON,使用排序鍵與精簡分隔符號重新序列化,也會產生完全相同的位元組。這兩種做法皆載於驗證指南

傳遞語意

這些語意適用於端點傳遞。舊版單一 URL 網路回呼僅會進行一次同步嘗試,不會重試。
每個事件會立即嘗試傳遞一次。任何 2xx 回應 都會確認傳遞。在任何其他結果下(非 2xx、 連線錯誤、逾時),我們會在第一次嘗試後的 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時、 12 小時及 24 小時重試——共 8 次嘗試,橫跨 24 小時。若每次嘗試皆失敗,傳遞將停止,端點 會在網路回呼端點中標示為 status="failing"。只要承載資料已被可靠地接受,請立即回傳 2xx; 並以非同步方式處理。
傳遞排序採盡力而為原則。實務上,我們會依照事件 發出的順序傳遞,但重試可能會在失敗後改變順序。 請一律依 call_id/物件 id 去除重複並進行協調。
傳遞為至少一次:在我們未收到回應後進行重試時, 可能會重複傳遞事件。每次重試都帶有相同的 event_id,因此請儲存已處理的 id 並略過重複項目。event_id 也會在各端點間共用——訂閱相同事件的兩個端點 會收到相同的 event_id
每次端點傳遞的逾時時間為 30 秒。在 舊版路徑上,會影響即時通話行為的阻塞式請求—— telephony.incoming / web.incoming 設定交換——會在 10 秒後逾時,但緩慢的 回應會延遲通話接聽,因此請盡量在幾秒內回應。 網路回呼模式的工具分派允許 20 秒。
外傳網路回呼來自 ThunderPhone 的雲端 IP 範圍。 若你的防火牆需要允許清單,請聯絡支援團隊,我們會 提供目前的範圍。

在舊版與端點式網路回呼之間選擇

新的整合應透過端點式 網路回呼接收事件。僅在你需要於接聽時動態設定通話, 或使用網路回呼模式的工具分派時,才保留(或新增)舊版 URL——這些 請求/回應交換僅會在舊版路徑上執行。

相關內容

事件目錄

所有事件類型及其承載資料。

網路回呼端點

管理多個端點、事件篩選條件及密鑰。

telephony.incoming / web.incoming

你的伺服器必須回應以設定通話的阻塞式請求。

telephony.complete / web.complete

包含文字記錄、錄音及指標的通話後承載資料。