回呼與簽章驗證
執行結束、有事要你們決定時,我們把事件送到 API 串接的回呼網址。用簽章金鑰驗證是我們送的。送不到會重送,最多 24 小時。
回呼是我們主動把事件送到你們系統的網址。這樣你們不用一直查詢,事情一發生就收到。
事件
| type | 什麼時候 | data |
|---|---|---|
workflow_run.finished |
這個串接開始的那一次結束(做完、失敗或取消) | 那一次,跟查詢的內容一樣 |
interaction.pending |
有事交給你們決定 | 那一則,見交給你們決定的事 |
interaction.expired |
那一則過期了 | 那一則 |
conversation.reply |
對話的回覆好了(wait 等不到、callback 模式、核准後接著做完) | 這一輪的回覆 |
conversation.handoff |
agent 把對話轉給你們的客服 | 對話編號、原因 |
message.created |
轉真人之後,使用者又傳了訊息 | 對話編號、內容 |
conversation.message |
Dot Agents 主控台的同事接手回覆 | 對話編號、內容 |
schedule_run.finished |
設定「做完送到 API 串接」的排程跑完一次 | 排程、成功或失敗、agent 說的話、檔案 |
test |
設定的人按了「測試」 | 一句說明 |
每一筆的內文:
{ "id": "c7d4…", "type": "workflow_run.finished", "created_at": "…", "data": { … } }
標頭
| 標頭 | 內容 |
|---|---|
x-dot-event |
事件的 type |
x-dot-delivery |
這一筆的編號。重送時編號不變,可以拿來去重 |
x-dot-timestamp |
送出的時間(秒) |
x-dot-signature |
sha256= 加上簽章 |
驗證簽章
簽章是用簽章金鑰,對「時間戳、一個點、原始內文」算 HMAC-SHA256。驗證時:
- 用收到的原始內文,不要先解析再轉回文字。
- 時間戳跟現在差太多(例如超過 5 分鐘)就丟掉,避免有人重放舊的請求。
- 用固定時間的比較函式比對簽章。
import { createHmac, timingSafeEqual } from 'node:crypto';
function verify(rawBody, headers, secret) {
const ts = headers['x-dot-timestamp'];
if (Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const want = 'sha256=' + createHmac('sha256', secret).update(`${ts}.${rawBody}`).digest('hex');
const got = headers['x-dot-signature'] ?? '';
return got.length === want.length && timingSafeEqual(Buffer.from(got), Buffer.from(want));
}
用 SDK 的話,直接呼叫 verifySignature(JavaScript)或 verify_signature(Python)。
回應與重送
- 回
2xx就算送達。請在 10 秒內回應。 - 其他狀態碼或逾時,我們會重送:1 分鐘、5 分鐘、15 分鐘、1 小時、3 小時,之後每 6 小時一次。
- 從第一次送出算起超過 24 小時,就不再送。建立這個串接的人會收到通知。
- 同一筆可能送到兩次,請用
x-dot-delivery去重。
串接上的 送出紀錄 列出最近 20 筆和結果。
相關頁
本頁對應 v0.168.0