跳到主要内容

Webhook 事件

回调要求​

  • 必须使用公网 HTTPS 地址；平台不跟随重定向。
  • 收到请求后尽快完成签名校验并返回 HTTP 2xx。
  • 复杂业务放入异步队列，避免因为处理超时触发重复投递。
  • 使用 eventId 做全局幂等；消息类事件同时使用业务 messageId 做幂等。

请求头​

X-Open-App-Id
X-Open-Event-Id
X-Open-Event-Type
X-Open-Timestamp
X-Open-Signature

签名​

Webhook 签名原文为：

eventId + "\n" + timestampMillis + "\n" + rawBody

使用 Webhook Secret 计算 HMAC-SHA256，输出小写十六进制。必须基于原始请求体计算，不能先解析 JSON 再序列化。

响应和重试​

返回任意 2xx 表示接收成功。非 2xx、连接失败或读取超时会进入指数退避重试；连续失败可能触发应用级熔断。业务处理失败时不要返回 2xx 后静默丢弃，应保存事件并由业务队列重试。

事件字段清单见事件模型。