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

# Webhook

<Info>
  您可以在开发者文档中找到更专业的集成指导：开发者文档 - [Webhook 集成指南](/zh/api-reference/guides/api-fundamentals/configure-webhooks)
</Info>

## 什么是 Webhook

Webhook 是一种 **事件驱动的 HTTP 回调机制**。当 YCloud 系统内发生特定事件时，它会主动通过 HTTPS 请求将事件数据推送到预先配置的 URL（即 Webhook 地址），从而无需频繁轮询接口。

## 创建 Webhook

### 1. 添加 Webhook 端点。

登录 **YCloud 控制面板**，前往 开发者 > Webhook，然后点击 添加端点 来创建 Webhook 端点。

<Frame caption="Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.">
  <img src="https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/developer-webhook-add-annotated.svg?fit=max&auto=format&n=gXEJIQXV2JH2VUQJ&q=85&s=6c04b793e7a8e7952e7931cd10232773" alt="高亮显示端点 URL 的空添加端点对话框。" width="3024" height="1656" data-path="product-assets/english-help-2026-09-22/developer-webhook-add-annotated.svg" />
</Frame>

### 2. 输入端点地址以监听相关事件。

YCloud 为 WhatsApp、SMS、Contact、Email 等提供了多种事件选项。

<Info>
  您可以在此处找到所有相关的事件 Payload：[Webhook Payload](/zh/api-reference/webhooks/test-webhooks)
</Info>

<Frame caption="Use Search event to find the subscriptions your endpoint needs.">
  <img src="https://mintcdn.com/lchnan/gXEJIQXV2JH2VUQJ/product-assets/english-help-2026-09-22/developer-webhook-events-annotated.svg?fit=max&auto=format&n=gXEJIQXV2JH2VUQJ&q=85&s=81cb1ab6ab3e979bb8ad6fdd9c4d4122" alt="包含事件名称和搜索事件的 Webhook 事件菜单。" width="3024" height="1656" data-path="product-assets/english-help-2026-09-22/developer-webhook-events-annotated.svg" />
</Frame>

### 3. 验证 Webhook 签名

<Info>
  请务必验证签名，以确保请求源自 YCloud 且未被篡改。
</Info>

使用端点的签名 `secret` 来验证 `YCloud-Signature` 请求头。请将密钥安全地存储在您的服务器上。有关端点密钥和验证流程，请参阅 [Webhook 集成指南](/zh/api-reference/guides/api-fundamentals/configure-webhooks)。

#### 签名格式：

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
YCloud-Signature: t={timestamp},s={signature}
```

#### 验证算法：

1. 从请求头中提取时间戳 (t) 和签名 (s)（时间戳为以秒为单位的 Unix 时间戳）。
2. 构建待签名 Payload：signed\_payload: `{timestamp}.{request_body}.`
3. 使用 HMAC-SHA256 算法计算签名：

   ```js theme={"theme":{"light":"github-light","dark":"github-dark"}}
   HMAC-SHA256(signed_payload, secret)
   ```
4. 将计算出的签名与接收到的签名进行比对。

### 4. 响应 Webhook

1. **返回 2xx 状态码** （例如 200、201、204）
   * 任何非 2xx 响应都会触发重试。
2. **快速响应** （建议在 6 秒内）
   * 快速响应会提高您的 Webhook 优先级。
   * 较慢的响应（>10 秒）可能会被降低优先级。
3. **异步处理** （推荐）
   * **立即** 返回 200 OK。
   * 在后台任务/队列中处理事件。

## 将 YCloud Webhook 发送 IP 加入白名单

YCloud 从以下服务器 IP 地址发送 Webhook 请求：

* `8.219.65.77`
* `47.236.160.49`

如果您的企业防火墙、网关或 Webhook 服务器按源 IP 限制入站流量，请将这两个地址添加到其白名单中。仅允许一个地址可能会导致部分 Webhook 发送被拦截。

<Note>
  IP 白名单属于附加的网络控制手段。对于每个 Webhook 请求，仍请继续验证 `YCloud-Signature` 请求头。
</Note>

## 查看 Webhook 发送日志

YCloud 会记录 Webhook 发送尝试，以便您确认事件是否已发送并对发送失败进行故障排查。

如果您的系统未收到预期的 Webhook，请在升级上报问题前先检查发送日志：

1. 在 YCloud 控制面板中，前往 **开发者** > **Webhook**。

2. 打开相关的 Webhook 端点并查看其发送日志。
   <img src="https://mintcdn.com/lchnan/7AejdQWTE_GcFoQy/images/image-21.png?fit=max&auto=format&n=7AejdQWTE_GcFoQy&q=85&s=5d979a36e16efc2e224bb68dafe64d89" alt="图片" width="2912" height="1578" data-path="images/image-21.png" />

3. 使用一个或多个筛选条件来查找发送记录：

* **状态**：显示发送成功或失败的记录。
* **事件**：按 Webhook 事件类型筛选。
* **事件 ID**：搜索特定的 YCloud 事件 ID。
* **数据 ID**：对于消息事件，输入消息 ID 以查找其发送记录。

4. 选择一条记录以查看发送时间、请求 Payload、响应体和 HTTP 状态码。

失败记录包含对应的发送失败原因。利用响应和错误详情来检查您的端点 URL、可用性、处理时间以及 HTTP 响应。

<Tip>
  当缺失预期的 Webhook 时，请先通过消息 ID 或事件 ID 搜索。这有助于区分是发送失败，还是事件未匹配端点的订阅配置。
</Tip>

失败的发送将根据下方的 [重试计划](#retry-mechanism) 自动重试。排查问题时，请在日志中查看最新的尝试记录。

## 常见问题

### 如果我配置了多个 Webhook URL，账户中每个 WABA 的事件都会发送到所有 URL 吗？

是的。在 **开发者** > **Webhook** 下配置的 Webhook 端点对整个 YCloud 账户全局生效。当账户中任意 WABA 的事件匹配所配置的事件订阅时，YCloud 都会将其发送到每个适用的 Webhook URL。

如果您需要将不同的 WABA 路由到不同的 Webhook URL，请使用[自定义应用](/zh/documentation/developer/create-and-configure-a-custom-app)。自定义应用允许您分配特定的 WhatsApp 电话号码，并为该应用配置专属的 Webhook 端点和事件订阅。

### 如果全部 7 次 Webhook 重试尝试都失败了会发生什么？

如果您的服务在第 7 次重试后仍未恢复，YCloud 将自动停止重试该事件。重试停止后，您的系统将不会自动接收到该事件。

恢复服务后，请联系 YCloud 支持团队请求重放 Webhook。重放可用性有限：YCloud 只能重新发送系统中仍然可用的事件，较早的历史事件可能不再支持重放。

<Warning>
  切勿将 Webhook 重放作为恢复策略。请监控您的端点，及时返回 `2xx` 状态，并尽快在 Webhook 投递日志中排查故障。
</Warning>

## 错误处理

### 重试机制：

如果您的服务返回非 2xx 状态码或未响应，YCloud 将自动重试：

* **重试计划**：10 秒 → 30 秒 → 5 分钟 → 30 分钟 → 1 小时 → 2 小时 → 2 小时。
* **最大重试次数**：7 次。
* **7 次失败后**：该事件将不再重试。

### URL 暂停：

为保护系统资源，频繁失败的 URL 将被暂时停用：

* **触发条件**：每分钟失败 200 次，或每分钟累计失败时间超过 10 分钟
* **暂停时长**：3 分钟
* **暂停期间**：不会发送任何 Webhook 请求
* **暂停结束后**：自动恢复


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