POST 請求——例如開始接聽來電、通話結束、評分作業完成、觸發警示等。提供 兩種傳送模式:
Webhook 端點(建議使用)
支援多個 URL、各端點專屬密鑰、各端點事件篩選,以及自動重試。
透過
GET/POST/PATCH/DELETE /v1/developer/webhook-endpoints 管理。單一 URL 舊版 webhook
每個組織一個 URL。承載通話生命週期事件,包括 阻塞式 組態交換。
透過
GET/PUT /v1/webhook 管理。telephony.incoming、telephony.complete、telephony.tool、
web.incoming、web.complete、web.tool)也會傳送至
舊版單一 URL webhook——如果你同時設定舊版 URL 與相符的端點,將在 兩個 路徑上都收到該事件。阻塞行為(telephony.incoming / web.incoming 組態
交換與 webhook 模式的
工具分派)僅存在於舊版路徑;每次端點傳送都是即發即棄的通知。
承載資料格式
端點傳送的內容是包含data、event_id 與
type 的 JSON 物件:
event_id 對每個發出的事件皆為唯一值。它在重試期間
以及 接收該事件的每個端點之間都完全相同——請依此去除重複事件。
舊版單一 URL webhook 會傳送相同的 type 與 data,但
不包含 event_id:
簽章驗證
每個請求都會在X-ThunderPhone-Signature 標頭中,帶有針對原始請求本文的 HMAC-SHA256 簽章。簽署金鑰為端點的 secret(若為舊版傳遞,則使用組織層級 webhook 的 secret)。
步驟
- 在進行任何剖析之前讀取原始請求本文。
- 計算
hmac_sha256(secret, body).hexdigest()。 - 以固定時間方式與
X-ThunderPhone-Signature標頭比較。
傳遞語意
這些語意適用於端點傳遞。舊版單一 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 秒。來源 IP
來源 IP
外傳網路回呼來自 ThunderPhone 的雲端 IP 範圍。
若你的防火牆需要允許清單,請聯絡支援團隊,我們會
提供目前的範圍。
在舊版與端點式網路回呼之間選擇
新的整合應透過端點式
網路回呼接收事件。僅在你需要於接聽時動態設定通話,
或使用網路回呼模式的工具分派時,才保留(或新增)舊版 URL——這些
請求/回應交換僅會在舊版路徑上執行。
相關內容
事件目錄
所有事件類型及其承載資料。
網路回呼端點
管理多個端點、事件篩選條件及密鑰。
telephony.incoming / web.incoming
你的伺服器必須回應以設定通話的阻塞式請求。
telephony.complete / web.complete
包含文字記錄、錄音及指標的通話後承載資料。
