Webhook 回调

异步任务完成后，系统主动向您指定的 URL 发送通知

工作原理

1. 创建异步任务时传入 webhook_url 参数
2. 任务完成后，系统向该地址发送 POST 请求
3. 您的服务接收回调并处理结果

回调请求格式

Headers

Content-Type: application/json
X-SeeAny-Signature: hmac-sha256-signature
X-SeeAny-Event: task.completed

Body

{
  "event": "task.completed",
  "task_id": "vid_20260603_001",
  "status": "completed",
  "result_url": "https://cdn.seeany.com/video/vid_001/output.mp4",
  "usage": {
    "cost": 0.70,
    "currency": "CNY"
  },
  "timestamp": 1748908920
}

失败回调

{
  "event": "task.failed",
  "task_id": "vid_20260603_001",
  "status": "failed",
  "error": {
    "code": "content_policy_violation",
    "message": "生成内容违反内容安全策略"
  },
  "timestamp": 1748908920
}

事件类型

事件	说明
task.completed	任务成功完成
task.failed	任务执行失败

签名验证

安全建议

请务必验证回调签名，防止伪造请求。

每个回调请求包含 X-SeeAny-Signature Header，使用 HMAC-SHA256 签名：

import hmac
import hashlib

WEBHOOK_SECRET = "your-webhook-secret"

def verify_webhook(payload_bytes: bytes, signature: str) -> bool:
    """验证 Webhook 签名"""
    expected = hmac.new(
        WEBHOOK_SECRET.encode(),
        payload_bytes,
        hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(expected, signature)

import crypto from "crypto";

const WEBHOOK_SECRET = "your-webhook-secret";

function verifyWebhook(payload: Buffer, signature: string): boolean {
  const expected = crypto
    .createHmac("sha256", WEBHOOK_SECRET)
    .update(payload)
    .digest("hex");
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

配置要求

要求	说明
HTTPS	回调地址必须使用 HTTPS
公网可访问	需要公网可达的 URL
响应 2xx	收到回调后应返回 2xx 状态码
幂等处理	同一 task_id 可能多次回调，需幂等处理
超时重试	回调超时（30s）会重试，最多 3 次

重试策略

重试次数	延迟
第 1 次	1 分钟后
第 2 次	5 分钟后
第 3 次	30 分钟后

提示

• 回调失败不影响任务结果，您可以随时通过 查询任务状态 获取
• 建议在回调处理中使用队列异步处理，避免阻塞响应
• 回调地址可在控制台统一配置，也可在请求中单独指定