运行 Webhook 事件接收示例
本页内容
使用 Python SDK 验签,将业务事件持久保存到本机 SQLite,再向平台确认接收。本教程帮助您验证订阅、重复投递与失败恢复。
了解示例完成的工作
本教程运行一个 Python 接收服务:验证平台通知,把业务事件保存到 SQLite,再返回回执。它适合验证订阅和接入流程,默认只监听本机回环地址;公网 HTTPS 由您已有的反向代理提供。
收到成功回执表示“事件已保存到接收端”,不表示您的后续业务已处理完。示例不主动付款、退款、签名或发布,也不连接平台数据库。需要同步修改自己的业务数据时,将去重与修改放在自己的同一事务中。
前提条件
- Python 3.10+,使用Python SDK 源码包中的
cloudsign/目录。 - 为自己的业务应用创建 Webhook 订阅,保存订阅 ID、独立回调密钥、应用 ID、来源与所选事件。回调密钥只在受限配置中保存。
- 准备公网 HTTPS 域名和有效证书,通过 443 端口将固定路径
/cloudsign/events转发到本机接收服务。关闭该路径的登录跳转、正文改写与缓存。 - 为事件数据库准备专用私有目录,位于网站根目录外。Linux 使用所属服务账号的 0700 目录、0600 文件;Windows 限制目录 ACL。不要使用生产业务数据库文件。
配置接收端
将 cloudsign_webhook_receiver.py 与 SDK 的 cloudsign/ 放在同一私有工作目录。使用进程环境或服务管理器传入以下配置,不把 Secret 写进命令、仓库或访问日志。
| 配置项 | 必填 | 说明 |
|---|---|---|
CLOUDSIGN_WEBHOOK_ID | 是 | 受信订阅的完整 WHK 标识。 |
CLOUDSIGN_WEBHOOK_SECRET | 是 | 该订阅的 CSW_ 回调密钥,不是 AccessKey Secret。 |
CLOUDSIGN_WEBHOOK_APP_ID | 是 | 绑定的业务应用 ID(A)。 |
CLOUDSIGN_WEBHOOK_SOURCE | 是 | 与订阅相同:api、website 或 website_upload。 |
CLOUDSIGN_WEBHOOK_EVENTS | 是 | 实际选中的业务事件,使用英文逗号分隔。地址验证自动允许,无需填写。 |
CLOUDSIGN_WEBHOOK_DB | 是 | 私有 SQLite 文件的绝对路径,例如私有工作目录下的 inbox/events.sqlite3。 |
CLOUDSIGN_WEBHOOK_PORT | 否 | 本机监听端口,默认 8900。监听地址固定为 127.0.0.1。 |
每个示例进程对应一个订阅。需要多个订阅时,分别配置接收路径和进程,或在自己的服务中实现固定的受信配置映射。不要从传入数据推测订阅来源。
python3 cloudsign_webhook_receiver.py启动后只输出回环地址。若配置无效或数据库目录权限过宽,进程会退出,不输出 Secret。正式运行时由服务管理器负责重启,反向代理设置请求大小、速率与超时限制;生产项目可将相同验签和持久事务逻辑接入已有框架。
验证订阅与第一条事件
- 确认反向代理完整保留四个签名头和未经修改的原始正文,拒绝重复签名头,不在公网暴露本机监听端口。
- 在开发者中心验证接收地址。示例验证
endpoint.challenge并生成 proof;挑战不写入业务事件表。 - 执行一项订阅已覆盖的操作。例如订阅 API 签名成功事件后,等待自己的签名任务完成。
- 在开发者中心确认投递成功,并检查本机
webhook_inbox中已保存该事件。读取正文中的资源 ID,继续查询原业务结果。
事件表保存订阅 ID、事件 ID、已验证正文、内容摘要及受信来源。不要把其中可能含业务信息的正文放进公开日志、下载目录或工单附件。
验证重复投递与失败恢复
同一事件重投时,签名和投递时间会变化。示例每次重新验签,再按订阅 ID 和事件 ID 去重;内容一致时返回原回执,不增加新记录。摘要在验签后根据事件内容计算,JSON 空白或字段顺序变化不会被误判为新业务。
同一事件 ID 对应不同内容、应用或受信来源时,示例返回 HTTP 409 并保留原记录。无法写入数据库时返回 HTTP 503,不发送成功回执。无效签名、过期投递时间或格式错误返回 400;未选中事件或应用不符返回 403。
使用测试订阅临时停止接收服务,可以检查平台失败重投;恢复后核对只产生一条事件记录。不要通过修改真实事件内容、重新付款或另建签名任务来测试重复投递。
接入自己的业务处理
后台任务从已保存的事件读取资源 ID,再查询平台当前状态,并以业务唯一键保证自己的处理幂等。事件入库成功后,如果后台处理失败,需要由您自己的任务重试;平台已经收到回执,不会替您的后台任务重跑。
示例未实现业务队列、消费状态、监控告警或历史清理。接入生产业务时,应根据自己的数据库、处理时长和留存要求补齐这些能力。保留通知原记录有助于对账,不能把它当作重复操作资金或权益的授权。