开发者文档中心

OpenAPI进入控制台

服务端 API 与回调 · 2026-10-31

Webhook:订阅、验签与回执

不同回调协议分别接入,不使用一个通用签名函数猜测所有协议。

订阅流程

  1. 在开放平台 Webhook 选择当前支持的事件及范围,填写 HTTPS 接收地址。将该订阅产生的签名密钥只放接收端。
  2. 保留请求原始正文,按对应协议的准确 Header、时间窗和签名算法校验;先核对协议再解析 JSON。
  3. 验签后持久化事件及唯一标识,原子去重后处理;重复投递不能重复创建业务对象。
  4. 通过投递尝试与业务记录分别核对接收、处理及最终结果;轮换密钥后按界面要求重新确认启用。

三类协议

来源查阅位置不可混用
平台 / 业务事件订阅X-Yunfu-Event-Id / X-Yunfu-Delivery-Id / X-Yunfu-Timestamp / X-Yunfu-Attempt / X-Yunfu-Signaturesha256= + hex(HMAC-SHA256(timestamp.raw_body));至少一次、不保序,自动投递最多 5 次含首次
通知投递X-Notification-Id;配置 HMAC 才附 X-Notification-Timestamp / X-Notification-Signaturesha256= + hex(HMAC-SHA256(timestamp.raw_body));没有自动 5 次重试
通信网关入站x-app-event-id / x-app-timestamp / x-app-signatureHMAC-SHA256(bindingId.eventId.timestamp.raw_body),64 位十六进制、不带 sha256=

验签实现

签名原文必须使用原始正文,不能先解析再序列化。时间戳使用 Unix 秒;业务事件和通信回调校验 ±300 秒窗口。业务回调示例见 examples/verify-business-callback.mjs;微信 XML、LINE、电话等仍按各自真实路由契约验签。/v1/webhooks/events 未实现,不作为订阅入口。

回执不是业务完成

接收端 2xx 只确认收到投递。把事件入队或通知发出也不能直接标为工单解决、退款完成或电话已结束。需要读取真实业务状态;未核对保持待跟进。

实现依据 · 仓库内路径
  • docs/OPEN-API-CALLBACKS.md
  • lib/developer-api/business-callback-contract.ts
  • lib/developer-docs/api-route-notes.ts

文档描述当前源码能力;不等于你的宿主或生产环境已通过验收。