跳到內容

Webhooks

配置 Webhook URL 後,文件翻譯任務(/jobs)結束時(成功或失敗)會通知你的伺服器。透過 POST /jobs/{id}/cancel 取消的任務不會發送回調。文檔操作與音視頻任務請輪詢各自的查詢介面。

透過 API 管理,每位用戶最多可擁有 3 個:

POST /api/v1/webhooks 创建
GET /api/v1/webhooks 列表
PATCH /api/v1/webhooks/{id} 更新 / 停用
DELETE /api/v1/webhooks/{id} 删除

建立範例:

Terminal window
curl -X POST https://omnidoc.top/api/v1/webhooks \
-H "X-API-Key: sk_your_key" \
-H "Content-Type: application/json" \
-d '{
"url": "https://your-server.com/hooks/omnidoc",
"secret": "your-signing-secret",
"events": ["job.completed"],
"description": "生产回调"
}'

URL 必須可從公網存取,建議使用 HTTPS;內網、本機位址和格式不正確的 URL 傳回 400。PATCH 可修改 url、secret、events、description 和 status(active / disabled)。

POST your-webhook-url
Content-Type: application/json
X-Webhook-Event: job.completed
X-Webhook-Timestamp: 1782900150
X-Webhook-Signature: sha256=...
{
"event": "job.completed",
"timestamp": 1782900150,
"data": {
"job_id": "q3f8s6c2a9m1k4tx",
"status": "completed",
"file_name": "report.docx",
"char_count": 12840
}
}
事件觸發時機
job.completed任務結束時觸發;data.status 為 completed 或 failed

失敗任務同樣走 job.completed 事件,通過 data.status == "failed" 與可選的 data.error 區分。成功任務不會返回 error 字段。data.char_count 為譯文字符數,失敗任務為 0。

events 僅接受 job.completed 與 *(訂閱全部事件),其他值或空清單回傳 422;PATCH 時未變更的欄位直接省略,傳 null 也回傳 422。

建立 Webhook 時填寫 secret 後,每次回調帶 X-Webhook-Signature。用 HMAC-SHA256 對 原始請求體 驗簽:

import hashlib
import hmac
import json
import time
def verify_webhook(payload: bytes, signature: str, secret: str) -> bool:
expected = hmac.new(
secret.encode(), payload, hashlib.sha256
).hexdigest()
return hmac.compare_digest(f"sha256={expected}", signature)
def parse_webhook(payload: bytes, signature: str, secret: str, tolerance: int = 12 * 3600) -> dict:
if not verify_webhook(payload, signature, secret):
raise ValueError("invalid signature")
event = json.loads(payload)
if abs(time.time() - event["timestamp"]) > tolerance:
raise ValueError("stale event")
return event

簽名僅覆蓋請求主體,不覆蓋請求標頭。防重放請在驗簽通過後檢查請求主體中的 timestamp(與 X-Webhook-Timestamp 相同,但只有前者受簽名保護),並按 data.job_id 與 data.status 去重。失敗重試時原樣重發首次投遞的請求主體,timestamp 不變,最後一次重試約在首次投遞 8.6 小時後,因此时效窗口不要短於這個時長(示例取 12 小時)。

  • 接收端須在 15 秒內回傳 2xx 才視為投遞成功;平台不跟隨重定向
  • 投遞失敗(超時、連線錯誤或非 2xx)會自動重試:在上一次失敗後分別等待 1 分鐘、5 分鐘、30 分鐘、2 小時、6 小時再投遞,每個事件最多投遞 6 次,仍失敗則不再投遞
  • 重試發往 Webhook 當前的 URL,請求體原樣不變(timestamp、data 與簽名都與首次相同;期間更換了 secret 時按新 secret 簽名);已投遞成功的事件不會再次發送
  • 當 Webhook 被停用、刪除或不再訂閱該事件後,尚未完成的重試隨之取消
  • 接收端應按 data.job_id 與 data.status 幂等處理,並在稳妥持久化後快速回應
  • 同一帳號的多個 Webhook 同時投遞,某個接收端變慢不會影響其他接收端
  • 連續 10 次投遞失敗(重試也計入)後,Webhook 會自動停用;修復接收端後通過 PATCH 重新啟用
  • 透過 GET /api/v1/webhooks 查看各 Webhook 的最近觸發時間、狀態碼和連續失敗次數