Webhook 回调

除了轮询状态接口，你还可以在提交视频任务时提供回调 URL，在生成完成时自动接收通知。

工作原理

提交时附带回调 URL：在提交视频任务时加入 callback_url
接收通知：任务完成（成功或失败）时，PoYo AI 会向你的 URL 发送 POST 请求
处理结果：你的服务器会收到完整的任务数据，包括生成的视频

回调请求

任务完成时，PoYo AI 会向你的回调 URL 发送 POST 请求。回调请求体与视频状态接口的任务数据结构相同，但不包含外层的 code 和 data 包装。

请求头

Content-Type: application/json
X-Webhook-Timestamp: 1783680000
X-Webhook-Signature: base64_hmac_sha256_signature

请求体

{
  "task_id": "task-unified-1757165211-xyz789",
  "status": "finished",
  "files": [
    {
      "file_url": "https://storage.poyo.ai/generated/video-xyz789.mp4",
      "file_type": "video"
    }
  ],
  "created_time": "2025-11-12T10:30:00",
  "error_message": null
}

失败任务回调

{
  "task_id": "task-unified-1757165031-uyujaw3d",
  "status": "failed",
  "files": [],
  "created_time": "2025-11-12T10:30:00",
  "error_message": "The prompt violates our content policy"
}

签名验证

PoYo 使用 HMAC-SHA256 对每个视频 Webhook 请求签名。现有接收端可以忽略这些请求头，但生产系统应当验证签名。获取你的 Webhook HMAC 密钥：

GET /api/api-keys/webhook-secret

轮换你的 Webhook HMAC 密钥：

POST /api/api-keys/webhook-secret/rotate

签名规则：

base64(HMAC-SHA256(task_id + "." + timestamp, webhook_hmac_key))

其中：

task_id 是回调请求体中顶层的 task_id
timestamp 是 X-Webhook-Timestamp 的值
webhook_hmac_key 由 GET /api/api-keys/webhook-secret 返回

要求

你的回调接口必须满足以下要求：

仅支持 HTTPS：必须使用 HTTPS 协议（不支持 HTTP）
URL 最大长度：2048 个字符
响应超时：必须在 30 秒内响应
成功响应：应返回 HTTP 200-299 状态码
禁止内网 IP：不能使用私有/内网 IP 地址（例如 192.168.x.x、10.x.x.x）
公网可访问：必须能从互联网公开访问

重试策略

如果你的回调接口未响应或返回错误：

重试次数：最多自动重试 5 次
重试间隔：指数退避，从约 60 秒开始，最长 10 分钟
最终失败：所有重试均失败后，不再继续重试

如果所有重试均失败，你仍可以通过轮询视频状态接口获取结果。

重要说明

验证请求：处理回调前先校验 X-Webhook-Timestamp 和 X-Webhook-Signature。

幂等性：将 Webhook 处理程序设计为幂等，以应对重复投递。

异步处理：异步处理回调并尽快返回 200，避免超时。

后续步骤

任务状态

了解如何轮询视频任务状态

视频模型

浏览所有视频模型

概览

任务管理

文件管理

账户管理

安全与最佳实践

Webhook 回调

Webhook 回调

工作原理

回调请求

请求头

请求体

失败任务回调

签名验证

要求

重试策略

重要说明

后续步骤

任务状态

视频模型

​Webhook 回调

​工作原理

​回调请求

​请求头

​请求体

​失败任务回调

​签名验证

​要求

​重试策略

​重要说明

​后续步骤

任务状态

视频模型

Webhook 回调

工作原理

回调请求

请求头

请求体

失败任务回调

签名验证

要求

重试策略

重要说明

后续步骤