> ## 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.

# Webhooks

> 配置异步任务回调

export const productUrls = JSON.parse('{"home":"https://www.vmeg.ai/home","apiConfiguration":"https://www.vmeg.ai/open-api-setting","signIn":"https://www.vmeg.ai/signIn?redirect=%2Fhome","signInToApiSettings":"https://www.vmeg.ai/signIn?redirect=%2Fopen-api-setting","signUp":"https://www.vmeg.ai/signup","account":"https://www.vmeg.ai/account","helpCenter":"https://www.vmeg.ai/help-center/","pricing":"https://www.vmeg.ai/pricing","myTasks":"https://www.vmeg.ai/my-tasks","myAssets":"https://www.vmeg.ai/my-assets","videoTranslation":"https://www.vmeg.ai/translation","audioTranslation":"https://www.vmeg.ai/audio-translation","cloneVoice":"https://www.vmeg.ai/clone-voice","bookDemo":"https://www.vmeg.ai/book-a-demo/","contactUs":"https://www.vmeg.ai/contact-us/","apiDocs":"https://docs.vmeg.ai"}');

export const apiKeyUrl = "https://www.vmeg.ai/open-api-setting";

## Webhook 是什么

**异步**任务完成时（TTS、文本翻译、声音克隆、音视频翻译），VMEG 向你配置的 URL 发送 **HTTP POST**。这是接收 **任务结果** 的方式 — `create-async` 的 HTTP 响应只确认受理（`taskId` 等）。

Webhook 是异步结果的 **投递机制**，不是独立产品。

## 为什么需要

| 未配置 Webhook                        | 已配置 Webhook    |
| ---------------------------------- | -------------- |
| `create-async` 只返回 `taskId`        | POST 请求体含完整交付物 |
| 需轮询 `GET /openapi/v1/tasks/detail` | 任务完成时主动通知你的服务  |

生产环境异步集成应在调用 `*-create-async` 前配置 Webhook。

## 配置

在 vmeg.ai 的 <a href={apiKeyUrl}>API 配置</a> 页（<a href={productUrls.signInToApiSettings}>登录</a>）：

1. 设置 **Webhook URL**（建议使用 HTTPS）。
2. 保存 URL 后，VMEG 会**自动生成 Webhook Secret** 并在同一页面展示。复制该 Secret 用于 [签名校验](/zh/guides/webhook-verification) — 无需自行设置。

可在同一页面测试连通性（若产品提供）。

## 接收端要求

你的接口必须：

1. **快速返回 2xx**（数秒内）。重逻辑放入队列或后台 worker。
2. **校验签名**（对原始请求体）— 见 [Webhook 签名校验](/zh/guides/webhook-verification)。
3. **按 JSON 中的 `pipelineKey` 去重**。同一异步完成的重试会携带相同的 `pipelineKey` — 见 [Webhook 请求体](/zh/guides/webhook-request#按-pipelinekey-去重)。若该键已处理过，仍应返回 2xx，但不要重复执行业务副作用。

非 2xx 或超时时，VMEG 会按退避策略重试。

## Webhook 请求体

任务完成时 POST JSON 带有 **`event`** 字段（如 `openapi-tts`），表示哪类产品结束。事件表与公共结构见 [Webhook 请求体](/zh/guides/webhook-request)。

各产品字段定义见 [API 参考](/zh/api-reference/introduction) 中对应 `create-async` 的 **Callbacks**。

## 相关

* [幂等](/zh/guides/idempotency) — 所有会改库的 POST 必填（含 `create-async`）
* [产品概览](/zh/guides/products/overview) — 各产品同步/异步对照