Webhooks

配置 Webhook URL 后，文件翻译任务（/jobs）结束时（成功或失败）会通知你的服务器。文档操作与音视频任务请轮询各自的查询接口。

管理 Webhook

通过 API 管理，每个用户最多 3 个：

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

创建示例：

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。

回调格式

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 字段。

events 只接受 job.completed 与 *（订阅全部事件），其他值或空列表返回 422；PATCH 时不改的字段直接省略，传 null 也返回 422。

签名验证

创建 Webhook 时填写 secret 后，每次回调带 X-Webhook-Signature。用 HMAC-SHA256 对原始请求体验签：

import hmac
import hashlib

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)

同时校验 X-Webhook-Timestamp 与当前时间的偏差（如 5 分钟内）防重放。

投递结果

• 接收端须在 15 秒内返回 2xx 才视为投递成功；平台不跟随重定向
• 当前每个事件只投递一次；接收端应将处理设计为幂等，并在稳妥持久化后快速响应
• 连续 10 次投递失败后，Webhook 会自动停用；修复接收端后通过 PATCH 重新启用
• 通过 GET /api/v1/webhooks 查看各 Webhook 的最近触发时间、状态码和连续失败次数