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

# Webhook 请求体

> 回调公共结构、event 字段与各产品载荷

## 是什么

**异步**任务完成后，VMEG 向你配置的 Webhook URL 发送 **HTTP POST**，请求体为 JSON。请按 [Webhook 签名校验](/zh/guides/webhook-verification) 校验 `X-Timestamp` 与 `X-Signature`。

`create-async` 的 HTTP 响应只表示受理（`taskId` 等）。**成品在 Webhook 请求体中返回**，不在该响应里。

## 公共结构

各类异步完成回调共用以下顶层字段；产品相关字段在 `data` 中：

```json theme={null}
{
  "code": 200,
  "version": "v1",
  "event": "openapi-tts",
  "pipelineKey": "a1b2c3d4e5f6789012345678901234ab",
  "message": "",
  "extraData": { "your": "memo" },
  "data": { }
}
```

| 字段            | 含义                              |
| ------------- | ------------------------------- |
| `code`        | 本次回调的业务结果（`200` 表示任务成功）         |
| `version`     | 任务的 API 版本号（如 `v1`、`v2`）        |
| `event`       | **哪类产品任务已完成** — 见下表             |
| `pipelineKey` | **该次异步完成的稳定标识** — 用于接收端去重（见下文）  |
| `message`     | `code` 非成功时的说明                  |
| `extraData`   | 异步提交时传入的 `extraData` 回显（若提交时有传） |
| `data`        | 任务结果；结构随 `event` 而异             |

## 按 `pipelineKey` 去重

VMEG 为每次**已受理**的异步任务分配一个 **`pipelineKey`**，并在该次完成的所有 Webhook POST 中携带。

| 情况                       | 处理方式                      |
| ------------------------ | ------------------------- |
| 首次见到某 `pipelineKey`      | 验签、处理 `data`、持久化该键、返回 2xx |
| 再次收到相同 `pipelineKey`（重试） | 快速返回 2xx；**不要**重复计费或不可逆操作 |

<Info>
  `pipelineKey` 用于 **Webhook 投递**去重，与 `create-async` 上的 [`X-Idempotency-Key`](/zh/guides/idempotency)（防止重复提交任务）不是同一概念。一次已受理的异步任务对应一个 `pipelineKey`；`data.taskId` 标识任务，但重试去重应以 `pipelineKey` 为准。
</Info>

## `event` 字段

`event` 是 **JSON 请求体里的字符串**，表示是哪条 Open API 产品线的异步任务已结束。请用它做路由（先根据 `event` 分支，再解析 `data`）。

<Note>
  [API 参考](/zh/api-reference/introduction) 里各 `create-async` 页面下的 **Callbacks** 区块名称来自 OpenAPI 工具命名。集成时请以 POST JSON 里的 **`event` 字段取值**为准，不要依赖该区块标题字面量。
</Note>

### 各产品对应的 `event`

| 产品                                             | `event` 取值                  | 异步创建接口                                                                           | `data` 中关注的内容                             |
| ---------------------------------------------- | --------------------------- | -------------------------------------------------------------------------------- | ----------------------------------------- |
| [文本转语音](/zh/guides/products/text-to-speech)    | `openapi-tts`               | [创建 TTS（异步）](/zh/api-reference/tts/create-tts-async)                             | 合成 `results`、`taskId` — 见该页 **Callbacks** |
| [文本翻译](/zh/guides/products/text-translation)   | `openapi-translate`         | [创建文本翻译（异步）](/zh/api-reference/text-translation/create-text-translation-async)   | `items`（译文列表）、`taskId`                    |
| [声音克隆](/zh/guides/products/voice-clone)        | `openapi-clone-voice`       | [创建声音克隆（异步）](/zh/api-reference/clone-voice/create-voice-clone-async)             | 成功时的 `voiceId` 等克隆字段                      |
| [音视频翻译](/zh/guides/products/media-translation) | `openapi-media-translation` | [创建媒体翻译（异步）](/zh/api-reference/media-translation/create-media-translation-async) | 交付物 CDN URL 等，见 `result`                  |

当前异步任务完成回调 **仅使用** 以上四种 `event`。若后续新增回调类型，会同步更新本文与各接口 **Callbacks** 说明。

### 处理示例

```text theme={null}
POST /your-webhook
  → 验签
  → 解析 JSON
  → 若 pipelineKey 已处理 → 返回 200
  → 按 event 分支：
       openapi-tts                 → 解析 TTS data
       openapi-translate           → 解析翻译 data
       openapi-clone-voice         → 解析克隆 data
       openapi-media-translation   → 解析媒体翻译 data
  → 记录 pipelineKey → 返回 200
```

## 各接口的请求 schema

字段类型与嵌套结构见 API 参考中各 `create-async` 操作下的 **Callbacks**（上表已链到对应页面）。