跳到內容

回呼與簽章驗證

執行結束、有事要你們決定時,我們把事件送到 API 串接的回呼網址。用簽章金鑰驗證是我們送的。送不到會重送,最多 24 小時。

回呼是我們主動把事件送到你們系統的網址。這樣你們不用一直查詢,事情一發生就收到。

你們的系統開始一次工作流、收到結果示意圖
做完時,我們把 workflow_run.finished 送到回呼網址。

事件

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。驗證時:

  1. 用收到的原始內文,不要先解析再轉回文字。
  2. 時間戳跟現在差太多(例如超過 5 分鐘)就丟掉,避免有人重放舊的請求。
  3. 用固定時間的比較函式比對簽章。
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