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

# Webhooks

> 在项目达到里程碑时立即接收 HTTP 回调，无需轮询

# Webhooks

Webhooks 让 VoiceCheap 能够在发生情况时立即通知您的服务器，因此您可以停止轮询
`GET /v1/translate/{projectId}/status`.

> [!NOTE]
>
> 每次投递只尝试一次，不会重试。对于不能错过的事件，请继续轮询状态。

## 设置

1. 在您的 VoiceCheap 账户中打开 [API 页面](https://app.voicecheap.ai/page-api)。
2. 在 **Webhook** 中选择 **生成签名密钥**。以 `whsec_` 开头的密钥只会显示一次；请复制并保存在您的服务器上。
3. 在 **端点 URL** 中输入 `https` URL，然后选择 **保存**。

就是这样。从那时起，您启动的每个项目都会向该端点发送事件。

> [!NOTE]
>
> Webhook URL 必须使用 443 端口的 HTTPS，并解析到公共网络地址。包含凭据或片段的
> URL、私有或保留地址以及重定向均会被拒绝。此规则适用于账户端点和项目级覆盖 URL。

通过操作 API 或 MCP 使用 `webhooks_get`、`webhooks_update` 和 `webhooks_delete`。`webhooks_create_secret` 只能通过 REST 操作 API 使用。收到签名密钥后请妥善保存；MCP 无法执行此操作，也无法轮询其结果。

### 按请求覆盖端点

`POST /v1/translate` 和 `POST /v1/projects` 接受一个可选的 `webhookUrl` 字段，该字段仅覆盖
该项目的账户端点。这对于将暂存流量发送到其他地方非常方便：

您还可以在 `POST /v1/projects/{projectId}/dub` 中设置 `webhookUrl`，更新现有项目的投递地址。

```bash theme={null}
curl -X POST "https://api.voicecheap.ai/v1/projects" \
  -H "x-api-key: vc_your-key" \
  -F "file=@interview.mp4" \
  -F "targetLanguage=german" \
  -F "webhookUrl=https://staging.your-server.com/voicecheap/webhooks"
```

签名密钥始终是账户密钥；只有目标会发生变化。

## 事件

| 事件 | 触发条件 |
| - | - |
| `project.created` | 项目已存在且其转录内容已存储。这是您下载 SRT 的提示。 |
| `project.creation.failed` | 无法创建项目。 |
| `project.translation.completed` | 翻译完成且输出已就绪。 |
| `project.translation.failed` | 翻译失败。 |
| `project.lipsync.completed` | 口型同步已完成。 |
| `project.lipsync.failed` | 口型同步失败。 |

> [!NOTE]
>
> 没有单独的转录事件。创建项目的请求会在转录完成前返回。`project.created` 只在转录保存后发送；此时可通过 [`POST /v1/projects/{projectId}/transcript`](https://api-docs.voicecheap.ai/docs/zh/api-reference/project-transcript) 获取转录。

## 有效载荷

每次交付都是一个带有 JSON 主体的 `POST`：

```json theme={null}
{
  "type": "project.created",
  "eventId": "evt_9f2c4b1d8e7a4c3f9b2d1e0a5c6b7d8e",
  "projectId": "7fa7d3a3-4f2b-4c1e-9a6d-2b3c4d5e6f70",
  "workflow": "transcription",
  "status": "success",
  "targetLanguage": "german",
  "error": null,
  "occurredAt": "2026-08-19T09:12:00.000Z"
}
```

| 字段 | 类型 | 描述 |
| - | - | - |
| `type` | string | 上述事件之一。 |
| `eventId` | string | 每个事件唯一。用于去重。 |
| `projectId` | string | 此事件所属的项目。 |
| `workflow` | string | `transcription` 或 `translation`。 |
| `status` | string | `success` 或 `failed`。 |
| `targetLanguage` | string | 仅在特定语言事件中出现。 |
| `error` | object \| null | 在 `*.failed` 事件中，与 REST API 具有相同的 `{ code, message }` 形状。请参阅 [错误代码](https://api-docs.voicecheap.ai/docs/zh/api-reference/errors.md)。 |
| `occurredAt` | string | ISO 8601 时间戳。 |

有效载荷特意保持精简。请调用 REST API 获取内容本身。

## 验证签名

每次交付都带有以下标头：

| 标头 | 描述 |
| - | - |
| `X-VoiceCheap-Signature` | `sha256=<hex>` — 有效载荷的 HMAC-SHA256，由您的签名密钥加密。 |
| `X-VoiceCheap-Timestamp` | Unix 秒数，包含在签名字符串中，以便您可以拒绝重放。 |
| `X-VoiceCheap-Event-Id` | 与主体中的 `eventId` 值相同，在支持请求中很有用。 |

签名涵盖了 `<timestamp>.<raw body>`，因此在每次交付时都不同，并证明了
请求来自 VoiceCheap 且主体在传输过程中未被修改。

```js theme={null}
import crypto from 'crypto';
import express from 'express';

const app = express();

// The raw body is required: parsing and re-serializing changes the bytes and the signature will
// never match. This is the single most common cause of failed verification.
app.post('/voicecheap/webhooks', express.raw({ type: 'application/json' }), (req, res) => {
  const rawBody = req.body.toString('utf8');
  const timestamp = req.header('X-VoiceCheap-Timestamp');
  const signature = req.header('X-VoiceCheap-Signature')?.replace('sha256=', '') ?? '';

  // Reject anything older than five minutes.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) {
    return res.status(400).send('Stale timestamp');
  }

  const expected = crypto.createHmac('sha256', process.env.VOICECHEAP_WEBHOOK_SECRET).update(`${timestamp}.${rawBody}`).digest('hex');

  const isValid = expected.length === signature.length && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));

  if (!isValid) return res.status(401).send('Invalid signature');

  const event = JSON.parse(rawBody);
  // Acknowledge quickly, then process asynchronously.
  res.status(200).send('ok');
  handleEvent(event);
});
```

> [!WARNING]
>
> 在信任交付之前验证签名。您的端点是一个公共 URL，而签名是 区分真实的 VoiceCheap 事件与到达该端点的任何其他内容的依据。

## 响应

回复任何 `2xx` 状态以进行确认。请在 **10 秒内** 回复 — 先确认并
在之后执行工作，而不是在回复之前进行处理。

非 2xx 响应或超时将被记录为交付失败，目前不会重试。

## 轮换密钥

在 API 页面上选择 **轮换 (Rotate)** 以生成新密钥。之前的密钥会立即
停止工作，因此请在轮换后尽快将新密钥部署到您的服务器。

删除 webhook 会同时移除端点和密钥，交付将停止。


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