Webhook 用于把智能任务和海外社媒的终态变化主动推送到你的服务端。它适合替代高频轮询，但不会改变原 API 的鉴权方式。

​
配置回调地址

  1. 登录控制台。
  2. 在首页打开“应用信息”中的“安全与回调配置”。
  3. 填写你的服务端 HTTPS 回调地址并保存。
  4. 确保该地址可从公网访问，并能在 6 秒内完成验签和返回确认响应。
每个应用当前配置一个回调地址；该应用产生的所有可通知事件都会发送到此地址。地址变更只影响之后创建的事件，已经进入重试的事件仍可能发送到原地址。 如果重置 APP_SECRET，之后的首次投递和失败重试都会立即使用新密钥生成签名。发布新密钥时应先让接收端在短暂切换期内识别新旧两把密钥，再移除旧密钥，避免重试中的事件验签失败。
注意 回调地址必须由你的服务端处理。不要使用需要浏览器 Cookie 的页面，也不要把 APP_SECRET 写入 URL、日志或错误信息。

​
平台发送的请求

平台使用 POST 发送 JSON，并附带以下请求头：
Webhook 请求体

​
验证签名

签名原文由请求头中的事件 ID、换行符和秒级时间戳组成：
计算规则：
接收端必须同时校验：
  • X-Webhook-Event-Id 与 JSON event_id 完全一致。
  • 使用常量时间比较校验签名，避免普通字符串比较造成时序泄漏。
  • 时间戳与服务器当前时间的差值在你的安全窗口内，例如 5 分钟。
  • event_id 未被成功处理过；重复事件直接返回成功确认，不再重复执行副作用。
完整 Node.js 与 Python 接收端见Webhook 接收端示例。

​
返回确认响应

验签并安全接收后，请在 6 秒内返回 HTTP 2xx 和以下 JSON：
只有 HTTP 为 2xx、JSON 同时包含 success 和 code，且 success=true、code=200 时才算投递成功。204 No Content、空响应、非 JSON、success=false 或其他业务码都会进入重试。
建议 推荐先完成验签与幂等落库，再立即返回确认；耗时业务交给你自己的队列异步处理，避免超过 6 秒。

​
重试与幂等

平台最多尝试 5 次。首次立即发送，失败后的重试间隔约为 10、20、40、80 秒。网络异常、超时、非 2xx、无效 JSON 或确认字段不符合要求都会触发重试。 接收端应以 event_id 建立唯一约束。出现重复投递时：
  1. 不再次创建订单、发消息或执行其他副作用。
  2. 如果此前已成功接收，仍返回 { "success": true, "code": 200 }。
  3. 仅记录事件 ID、事件类型和处理状态；不要记录 APP_SECRET 或完整签名。

​
上线检查

  • 回调地址为可公开访问的 HTTPS 地址。
  • 读取原始请求头后先做时间窗、事件 ID 和签名校验。
  • 使用数据库唯一键或同等机制保证 event_id 幂等。
  • 6 秒内返回 HTTP 2xx 与正确 JSON 确认。
  • 将真正业务处理放入异步队列。
  • 对验签失败、重复事件和处理失败设置可观测告警，但不记录密钥。