Skip to main content

​
事件类型

​
通用结构

所有 Webhook 使用相同的请求结构：

​
PAYMENT_NOTIFICATION

支付完成或失败时通知。 通知体的 eventType 固定为 PAYMENT_NOTIFICATION。result 的结构与 Order Inquiry 响应的 data 一致。请以 API 文档中的完整响应结构为准。

​
Subscription 支付事件

Subscription 场景下，使用 result.subscriptionInfo.subscriptionEvent 区分支付通知对应的业务： 这些值是 subscriptionEvent 的取值，通知的 eventType 仍为 PAYMENT_NOTIFICATION。
周期权益发放：建议使用 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION 触发周期权益发放检查。先验签，核对 Subscription、周期、当期应付金额和最终支付成功状态后，再按 subscriptionId 和周期幂等发放对应权益。不要仅凭收到 PAYMENT_NOTIFICATION 或 subscriptionEvent 的取值发放权益。USER_ADD_PAYMENT_METHOD 和 TOPUP_CHARGE 应分别处理，不要将它们当作新周期扣款或新周期权益的发放依据。完整处理建议见 Subscription 权益发放。

​
REFUND_NOTIFICATION

退款完成后通知，发送到创建退款时的 refundNotifyUrl。 通知体的 eventType 固定为 REFUND_NOTIFICATION。result 的结构与 Refund Inquiry 响应的 data 一致。请以 API 文档中的完整响应结构为准。

​
CHARGEBACK_NOTIFICATION

Chargeback 创建或状态变更时通知，发送到 Portal 中配置的 chargebackNotifyUrl。 通知体的 eventType 固定为 CHARGEBACK_NOTIFICATION。result 的结构与 Chargeback Inquiry 响应的 data 一致。请以最新通知中的 chargebackStatus 为准。

​
WITHDRAW_NOTIFICATION

商户通过 /api/v1/withdraw/create 发起的提现成功或失败时通知，发送到该请求中的 notifyUrl（必填）。 通知体的 eventType 固定为 WITHDRAW_NOTIFICATION。result 的结构与 /api/v1/withdraw/inquiry 的响应结构相同；接口与状态说明见提现与余额 API。 收到通知后，先验签，再调用 /api/v1/withdraw/inquiry 查询最新状态，并以查询结果为准。商户响应格式见本页商户响应，重试规则见重试与失败恢复。

​
TOKENIZATION_NOTIFICATION

Tokenization 完成、Token 状态变更或 Token 卡片信息更新时通知，发送到调用 Generate Token 时传入的 notifyUrl。 通知体的 eventType 固定为 TOKENIZATION_NOTIFICATION。result 的结构与 Token Inquiry 响应 data 数组中的单个对象一致。请以 API 文档中的完整响应结构为准。 请以 result.tokenId 为幂等键处理通知，并使用每次通知中的最新值更新本地保存的 tokenStatus 和 Token 数据。

​
SUBSCRIPTION_STATUS_NOTIFICATION

当 Subscription 主单状态发生变更时通知（激活、取消、关闭）。 通知体的 eventType 固定为 SUBSCRIPTION_STATUS_NOTIFICATION。result 的结构与 Subscription Inquiry 响应的 data 一致。请以 API 文档中的完整响应结构为准。 SDK 中可使用两种处理器：
  • onSubscriptionStatus() — 直接处理此事件
  • onSubscriptionPayment() — 当 onSubscriptionStatus 未注册时的降级处理

​
SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION

通知 Subscription 周期的最终支付结果，例如第 2 期、第 3 期的续费结果。重试过程中不通知，仅通知当期最终结果。如果只关心每期订单的终态而不想关注当期多次重试，监听此事件。 通知体的 eventType 固定为 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION。result 的结构与 Subscription Inquiry 响应的 data 一致。请以 API 文档中的完整响应结构为准。

​
SUBSCRIPTION_CHANGE_NOTIFICATION

订阅变更（升降级）完成时通知。 通知体的 eventType 固定为 SUBSCRIPTION_CHANGE_NOTIFICATION。result 的结构与 Subscription Change Inquiry 响应的 data 一致。请以 API 文档中的完整响应结构为准。

​
商户响应

所有 Webhook 必须返回 HTTP 200，body 为 {"message":"success"}。
Waffo 同时检查 HTTP 状态码和响应 body。如果响应格式不正确，Waffo 会认为通知投递失败并重试。

​
使用 SDK（推荐）

SDK 的 handleWebhook() 方法自动处理签名验证、事件路由和响应 body 构建：

​
手动响应

如不使用 SDK，响应 body 必须是以下之一：
  • {"message":"success"} — 已成功处理
  • {"message":"failed"} — 处理失败，Waffo 将重试
  • {"message":"unknown"} — 状态未知，Waffo 将重试
重试策略：failed 或 unknown 时，Waffo 最多重试 8 次（含首次），间隔从 30 秒递增到 8 小时。详见 重试与失败恢复。

​
订阅通知选择指南

订阅场景涉及三类通知，按需选择监听：
SUBSCRIPTION_STATUS_NOTIFICATION 和 SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION 都是异步分发的 Webhook，受队列消费、重试、网络延迟等影响，到达顺序不保证；不要把回调到达顺序作为业务状态机依据。正确的处理方式（幂等去重、收到任一回调后先调用 subscription/inquiry 查询最终状态）见 处理最佳实践。
典型组合推荐：
  • 最小集成：监听 SUBSCRIPTION_STATUS_NOTIFICATION + SUBSCRIPTION_PERIOD_CHANGED_NOTIFICATION
  • 完整集成：三种都监听，用 PAYMENT_NOTIFICATION 获取每次重试的详细失败原因
权益发放建议及幂等校验见 Subscription 权益发放。