> ## Documentation Index
> Fetch the complete documentation index at: https://docs.poyo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook 回调

> 视频任务完成时自动接收通知

# Webhook 回调

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

## 工作原理

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

## 回调请求

任务完成时，PoYo AI 会向你的回调 URL 发送 POST 请求。回调请求体与[视频状态接口](https://docs.poyo.ai/zh/api-manual/task-management/video-status.md)的任务数据结构相同，但不包含外层的 `code` 和 `data` 包装。

### 请求头

```http theme={"dark"}
Content-Type: application/json
X-Webhook-Timestamp: 1783680000
X-Webhook-Signature: base64_hmac_sha256_signature
```

### 请求体

```json theme={"dark"}
{
  "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
}
```

### 失败任务回调

```json theme={"dark"}
{
  "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 密钥：

```bash theme={"dark"}
GET /api/api-keys/webhook-secret
```

轮换你的 Webhook HMAC 密钥：

```bash theme={"dark"}
POST /api/api-keys/webhook-secret/rotate
```

签名规则：

```text theme={"dark"}
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 分钟
* **最终失败**：所有重试均失败后，不再继续重试

> [!WARNING]
>
> 如果所有重试均失败，你仍可以通过轮询[视频状态接口](https://docs.poyo.ai/zh/api-manual/task-management/video-status.md)获取结果。

## 重要说明

> [!TIP]
>
> **验证请求**：处理回调前先校验 `X-Webhook-Timestamp` 和 `X-Webhook-Signature`。

> [!TIP]
>
> **幂等性**：将 Webhook 处理程序设计为幂等，以应对重复投递。

> [!TIP]
>
> **异步处理**：异步处理回调并尽快返回 200，避免超时。

## 后续步骤

> **[任务状态](https://docs.poyo.ai/zh/api-manual/task-management/video-status.md)**
>
> 了解如何轮询视频任务状态

> **[视频模型](https://docs.poyo.ai/zh/api-manual/video-series/overview.md)**
>
> 浏览所有视频模型


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.