立即注册

Webhook 回调

Webhook 回调

异步任务（/api/ai/tasks 或供应商原生接口兼容异步场景）可在提交时设置 callbackUrl，任务完成/失败/进度更新时平台向你的服务器 POST 通知。

1. 配置方式

提交任务时传入：

{
  "modelKey": "nano-banana",
  "callbackId": "order-20260618-001",
  "callbackUrl": "https://your-server.com/webhook/jellytoken",
  "imageParams": {
    "prompt": "..."
  }
}
字段说明
modelKey模型 ID（平台异步 API 请求字段名）
callbackUrl你的 HTTPS 接收地址
callbackId幂等 ID，回调 payload 中原样返回

2. 回调 Payload

平台 POST JSON（snake_case）：

{
  "callback_id": "order-20260618-001",
  "status": "completed",
  "result_url": "https://cdn.example.com/result.mp4",
  "result_content": null,
  "error": null,
  "error_code": null,
  "timestamp": "2026-06-18T12:00:00.000Z",
  "usage": {
    "promptTokens": 0,
    "completionTokens": 0,
    "totalTokens": 0
  },
  "external_data": {},
  "progress": 100
}

status 取值

status说明
progress进行中（含 progress 0–100）
completed成功
failed失败，见 error / error_code
cancelled已取消

结果字段

字段说明
result_url结果文件地址
result_contentTEXT 类任务正文结果
error_code失败时稳定错误码

3. 签名验证

回调请求头：

X-AI-Service-Signature: <hmac-sha256-hex>
X-AI-Service-Timestamp: <ISO8601>
Content-Type: application/json

验签算法

signature = HMAC-SHA256(webhook_secret, JSON.stringify(payload))
  • webhook_secret 由平台为账号配置（联系运营或查看控制台说明）
  • 对比 X-AI-Service-Signature 与计算结果（常量时间比较）

伪代码

import hmac
import hashlib
import json

def verify(payload: dict, signature: str, secret: str) -> bool:
    body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False)
    expected = hmac.new(
        secret.encode(),
        body.encode(),
        hashlib.sha256,
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

4. 接收端要求

  1. HTTPS 公网可达
  2. 5 秒内 返回 HTTP 2xx，否则可能重试
  3. 幂等：同一 callback_id 可能重复投递，请去重
  4. 验签失败应返回 401，勿处理业务

5. 与轮询配合

模式适用
仅 Webhook生产推荐
Webhook + 轮询兜底高可靠场景
仅轮询开发调试

轮询：GET /api/ai/tasks/{taskId}（taskId 见提交响应）

6. 故障排查

现象检查
未收到回调URL 是否 HTTPS、防火墙、证书
签名失败secret 是否一致、JSON 序列化是否一致
failederror_code 对照 错误码

相关文档