您可以在开发者文档中找到更专业的集成指导：开发者文档 - Webhook 集成指南
什么是 Webhook
Webhook 是一种 事件驱动的 HTTP 回调机制。当 YCloud 系统内发生特定事件时，它会通过 HTTPS 请求主动将事件数据推送到预先配置的 URL（Webhook 地址），从而无需频繁进行接口轮询。创建 Webhook
1. 添加 Webhook 端点。
登录 YCloud 控制台，前往开发者 > Webhooks，然后点击添加端点以创建 Webhook 端点。
Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.
2. 输入端点地址以监听相关事件。
YCloud 为 WhatsApp、SMS、Contact、Email 等提供了多种事件选项。您可以在此处找到所有相关的事件有效负载：Webhook 有效负载
Use Search event to find the subscriptions your endpoint needs.
3. 验证 Webhook 签名
务必始终验证签名，以确保请求来自 YCloud 且未被篡改。
secret 验证 YCloud-Signature 请求头。请将密钥安全地存储在您的服务器上。有关端点密钥和验证流程，请参阅 Webhook 集成指南。
签名格式：
验证算法：
- 从请求头中提取时间戳 (t) 和签名 (s)（时间戳是以秒为单位的 Unix 时间戳）。
-
使用完全一致的原始请求体构建待签名有效负载
{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 控制台中，前往 开发者 > Webhooks。
-
打开相应的 Webhook 端点并查看其发送日志。
- 使用一个或多个筛选条件查找发送记录：
- 状态：显示成功或失败的发送。
- 事件：按 Webhook 事件类型筛选。
- 事件 ID：搜索特定的 YCloud 事件 ID。
- 数据 ID：对于消息事件，输入消息 ID 即可查找其发送记录。
- 选择一条记录以查看发送时间、请求有效负载、响应体和 HTTP 状态码。
常见问题
如果我配置了多个 Webhook URL，账户中所有 WABA 的事件都会发送到这些地址吗？
是的。在 开发者 > Webhooks 下配置的 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 请求
- 暂停结束后：自动恢复