回呼(Webhook)

建立任務時帶上 callback_url(需以 https:// 開頭),任務完成或失敗時,系統會主動用 POST 通知你的伺服器,不需要一直查詢任務狀態。

什麼時候會通知

• 任務完成(status = 20)時通知一次。
• 任務失敗(status = 30)時通知一次。失敗的任務積分已自動退回,見〈積分與計費〉。
• 任務被取消時不會通知。

通知內容

POST {你的 callback_url}
Content-Type: application/json
X-Signature: <HMAC-SHA256 簽名,見下方>
X-Timestamp: 1799999999

{
  "public_id": "01JABCXYZULID",
  "status": 20,
  "error_code": null,
  "payload": null
}

通知只包含任務狀態(status 的意思請見〈任務查詢與取件〉),不包含 result 和 files。收到通知後,請呼叫 GET /api/tasks/{public_id} 取得完整結果。

payload 是你建立任務時送出的 payload,原樣帶回,沒帶的話是 null。可以用來放訂單編號這類你自己的資料。

例外:人臉年齡偵測的通知會多帶 result,直接附上偵測結果,詳見〈人臉年齡偵測〉。其他任務的通知就是上面這四個欄位。

驗證簽名

X-Signature 是用你帳號的 Webhook 密鑰,對原始 request body 做 HMAC-SHA256 計算出來的十六進位字串:

X-Signature = hash_hmac('sha256', <raw request body>, <your webhook_secret>)

Node.js 驗證範例:

const crypto = require('crypto')

function isValidSignature(rawBody, signatureHeader, webhookSecret) {
    const expected = crypto.createHmac('sha256', webhookSecret).update(rawBody).digest('hex')
    return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader))
}

請用收到的原始 body 字串計算簽名,不要用重新轉換過的 JSON,否則欄位順序或空白不同就會對不上。

X-Timestamp 是送出當下的 Unix 時間戳記。要不要檢查時間來防止重放攻擊,由你自行決定,系統不會檢查。

查看與更換 Webhook 密鑰

Webhook 密鑰是帳號層級的設定,同一個帳號的所有任務共用一組,可以在後台的Webhook頁面查看或更換。

更換後舊密鑰會立即失效,沒有過渡期。新密鑰在更換當下才會產生,所以請在更換後馬上更新你伺服器上的設定。從更換到更新設定之間收到的通知會驗證失敗,但系統會自動重送(見下方〈重送規則〉),更新完成後就能用新密鑰收到這些通知。

重送規則

通知送出失敗(逾時、連線失敗,或你的伺服器回應不是 2xx)時,系統會自動重送,間隔會逐次拉長:

第幾次重送	與上一次的間隔
1	1 分鐘
2	5 分鐘
3	30 分鐘
4	2 小時
5	6 小時

重送 5 次仍失敗就會停止。同一個 public_id 和 status 的通知可能會收到不只一次,請確保重複收到時不會重複處理。