Webhook 回调失败、重试与幂等设计
说明平台事件推送的失败重试机制、投递日志排查方式,以及接收端应如何实现幂等避免重复处理。
事件推送与重试
当您的回调地址返回非 2xx 状态码或超时时,平台会按既定策略自动重试投递;每次投递的状态、尝试次数与下次重试时间都会记录在投递日志中,可在管理后台按事件类型、状态筛选查询,也支持对单条记录发起手动重试或发送测试事件验证端点可达性。
常见事件类型
平台目前支持推送 subscription.created(订阅创建)、subscription.renewed(续费)、subscription.upgraded(升级)、subscription.expired(到期)、subscription.cancelled(取消)、subscription.suspended(暂停)、tenant.cancelled(租户注销)等业务事件。
接收端幂等设计
请在接收端根据事件中的业务单号或订阅 ID 做去重处理,避免因平台重试导致同一事件被重复消费(如重复发货、重复记账)。建议返回 2xx 状态码前完成幂等校验,处理逻辑本身可异步执行。