跳转到主要内容
您可以在开发者文档中找到更专业的集成指导:开发者文档 - Webhook 集成指南

什么是 Webhook

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

创建 Webhook

1. 添加 Webhook 终端节点。

登录 YCloud 控制台,前往开发者 > Webhooks,然后点击添加终端节点以创建 Webhook 终端节点。
高亮显示终端节点 URL 的空白添加终端节点对话框。

Enter your HTTPS endpoint URL, add an optional description, and choose the events before confirming.

2. 输入终端节点地址以监控相关事件。

YCloud 为 WhatsApp、SMS、Contact、Email 等提供多种事件选项。
您可以在此处找到这些事件的所有相关载荷:Webhook 载荷
包含事件名称和搜索事件的 Webhook 事件菜单。

Use Search event to find the subscriptions your endpoint needs.

3. 验证 Webhook 签名

务必验证签名,以确保请求来自 YCloud 且未被篡改。
使用终端节点的签名 secret 验证 YCloud-Signature 请求头。请在您的服务器上安全存储该密钥。有关终端节点密钥和验证工作流程,请参阅 Webhook 集成指南。

签名格式:

验证算法:

  1. 从请求头中提取时间戳 (t) 和签名 (s)(时间戳为以秒为单位的 Unix 时间戳)。
  2. 使用完全相同的原始请求体将待签名载荷构造为 {timestamp}.{request_body}。请勿在请求体后添加句点。
  3. 使用 HMAC-SHA256 算法计算签名:
  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 推送被拦截。
IP 白名单是一项额外的网络控制措施。对于每个 Webhook 请求,请继续验证 YCloud-Signature 请求头。

查看 Webhook 推送日志

YCloud 会记录 Webhook 推送尝试,以便您确认事件是否已发送并排查推送故障。 如果您的系统未收到预期的 Webhook,请在升级上报问题前先检查推送日志:
  1. 在 YCloud 控制台中,前往 开发者 > Webhooks。
  2. 打开相关的 Webhook 终端节点并查看其推送日志。 图片
  3. 使用一个或多个筛选条件查找推送记录:
  • 状态:显示成功或失败的推送。
  • 事件:按 Webhook 事件类型筛选。
  • 事件 ID:搜索特定的 YCloud 事件 ID。
  • 数据 ID:对于消息事件,输入消息 ID 即可找到其推送记录。
  1. 选择一条记录以查看推送时间、请求载荷、响应体和 HTTP 状态码。
失败的记录会包含相应的推送失败原因。利用响应和错误详情来检查终端节点 URL、可用性、处理时间以及 HTTP 响应。
当预期的 Webhook 丢失时,请先按消息 ID 或事件 ID 搜索。这有助于区分推送失败还是事件未匹配终端节点的订阅配置。
失败的推送将根据下方的重试计划自动重试。排查问题时,请在日志中查看最新的尝试记录。

常见问题

如果我配置了多个 Webhook URL,账户中所有 WABA 的事件都会发送到所有这些 URL 吗?

是的。在 开发者 > Webhooks 下配置的 Webhook 终端节点在 YCloud 账户级别是全局生效的。当该账户中任何 WABA 的事件匹配所配置的事件订阅时,YCloud 都会将其发送到每个适用的 Webhook URL。 如果您需要将不同的 WABA 路由到不同的 Webhook URL,请使用自定义应用。通过自定义应用,您可以分配特定的 WhatsApp 电话号码,并为该应用配置专用的 Webhook 终端节点及事件订阅。

如果全部 7 次 Webhook 重试都失败了会怎么样?

如果您的服务在第 7 次重试后仍未恢复,YCloud 将自动停止重试该事件。重试停止后,您的系统将不会自动接收到该事件。 恢复服务后,请联系 YCloud 支持团队申请重放 Webhook。重放可用性有限:YCloud 只能重发系统中仍然可用的事件,较早的历史事件可能不再支持重放。
请勿将 Webhook 重放作为恢复策略。请监控您的端点,及时返回 2xx 状态,并尽快排查 Webhook 投递日志中的失败原因。

错误处理

重试机制:

如果您的服务返回非 2xx 状态码或未响应,YCloud 将自动重试:
  • 重试时间间隔:10 秒 → 30 秒 → 5 分钟 → 30 分钟 → 1 小时 → 2 小时 → 2 小时。
  • 最大重试次数:7 次。
  • 失败 7 次后:该事件将不再重试。

URL 暂停:

为保护系统资源,频繁失败的 URL 将被暂时停用:
  • 触发条件:每分钟失败 200 次或每分钟累计失败时间超过 10 分钟
  • 暂停时长:3 分钟
  • 暂停期间:不会发送任何 Webhook 请求
  • 暂停结束后:自动恢复