您可以在开发者文档中找到更专业的集成指导：开发者文档 - Webhook 集成指南
什么是 Webhook
Webhook 是一种 事件驱动的 HTTP 回调机制。当 YCloud 系统内发生特定事件时，它会主动通过 HTTPS 请求将事件数据推送到预先配置的 URL（即 Webhook 地址），从而无需频繁轮询接口。创建 Webhook
1. 添加 Webhook 端点。
登录 YCloud 控制面板，前往 开发者 > Webhook，然后点击 添加端点 来创建 Webhook 端点。
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. 输入端点地址以监听相关事件。
YCloud 为 WhatsApp、SMS、Contact、Email 等提供了多种事件选项。您可以在此处找到所有相关的事件 Payload：Webhook Payload
Use Search event to find the subscriptions your endpoint needs.
3. 验证 Webhook 签名
请务必验证签名，以确保请求源自 YCloud 且未被篡改。
secret 来验证 YCloud-Signature 请求头。请将密钥安全地存储在您的服务器上。有关端点密钥和验证流程，请参阅 Webhook 集成指南。
签名格式：
验证算法：
- 从请求头中提取时间戳 (t) 和签名 (s)（时间戳为以秒为单位的 Unix 时间戳）。
-
构建待签名 Payload：signed_payload:
{timestamp}.{request_body}. -
使用 HMAC-SHA256 算法计算签名：
- 将计算出的签名与接收到的签名进行比对。
4. 响应 Webhook
- 返回 2xx 状态码 （例如 200、201、204）
- 任何非 2xx 响应都会触发重试。
- 快速响应 （建议在 6 秒内）
- 快速响应会提高您的 Webhook 优先级。
- 较慢的响应（>10 秒）可能会被降低优先级。
- 异步处理 （推荐）
- 立即 返回 200 OK。
- 在后台任务/队列中处理事件。
将 YCloud Webhook 发送 IP 加入白名单
YCloud 从以下服务器 IP 地址发送 Webhook 请求：8.219.65.7747.236.160.49
IP 白名单属于附加的网络控制手段。对于每个 Webhook 请求，仍请继续验证
YCloud-Signature 请求头。查看 Webhook 发送日志
YCloud 会记录 Webhook 发送尝试，以便您确认事件是否已发送并对发送失败进行故障排查。 如果您的系统未收到预期的 Webhook，请在升级上报问题前先检查发送日志：- 在 YCloud 控制面板中，前往 开发者 > Webhook。
-
打开相关的 Webhook 端点并查看其发送日志。
- 使用一个或多个筛选条件来查找发送记录：
- 状态：显示发送成功或失败的记录。
- 事件：按 Webhook 事件类型筛选。
- 事件 ID：搜索特定的 YCloud 事件 ID。
- 数据 ID：对于消息事件，输入消息 ID 以查找其发送记录。
- 选择一条记录以查看发送时间、请求 Payload、响应体和 HTTP 状态码。
常见问题
如果我配置了多个 Webhook URL，账户中每个 WABA 的事件都会发送到所有 URL 吗？
是的。在 开发者 > Webhook 下配置的 Webhook 端点对整个 YCloud 账户全局生效。当账户中任意 WABA 的事件匹配所配置的事件订阅时，YCloud 都会将其发送到每个适用的 Webhook URL。 如果您需要将不同的 WABA 路由到不同的 Webhook URL，请使用自定义应用。自定义应用允许您分配特定的 WhatsApp 电话号码，并为该应用配置专属的 Webhook 端点和事件订阅。如果全部 7 次 Webhook 重试尝试都失败了会发生什么？
如果您的服务在第 7 次重试后仍未恢复，YCloud 将自动停止重试该事件。重试停止后，您的系统将不会自动接收到该事件。 恢复服务后，请联系 YCloud 支持团队请求重放 Webhook。重放可用性有限：YCloud 只能重新发送系统中仍然可用的事件，较早的历史事件可能不再支持重放。错误处理
重试机制：
如果您的服务返回非 2xx 状态码或未响应，YCloud 将自动重试：- 重试计划：10 秒 → 30 秒 → 5 分钟 → 30 分钟 → 1 小时 → 2 小时 → 2 小时。
- 最大重试次数：7 次。
- 7 次失败后：该事件将不再重试。
URL 暂停：
为保护系统资源，频繁失败的 URL 将被暂时停用：- 触发条件：每分钟失败 200 次，或每分钟累计失败时间超过 10 分钟
- 暂停时长：3 分钟
- 暂停期间：不会发送任何 Webhook 请求
- 暂停结束后：自动恢复