跳转到主要内容

Documentation Index

Fetch the complete documentation index at: https://waffo.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Webhook 是 Waffo 向商户推送异步事件通知的机制。当支付状态发生变化时，Waffo 会向商户的 notifyUrl 发送一条 HTTPS POST 请求。

​
为什么使用 Webhook

  • 支付结果的权威来源（优先级高于跳转与轮询）
  • 异步通知，不会阻塞用户流程
  • 覆盖所有状态变更事件

​
配置要求

要求描述
协议HTTPS（TLS 1.2+）
可达性可通过公网访问
签名Waffo 使用 Waffo 私钥对请求 body 签名；商户必须使用 Waffo 公钥验证 X-SIGNATURE
响应签名商户响应也必须使用商户私钥签名
响应 body{"message": "success"} / {"message": "failed"} / {"message": "unknown"}

​
Webhook 请求结构

{
  "header": {
    "Content-Type": "application/json",
    "X-SIGNATURE": "..."
  },
  "body": {
    "eventType": "PAYMENT_NOTIFICATION",
    "result": { ... }
  }
}

​
商户响应

{
  "header": {
    "Content-Type": "application/json",
    "X-SIGNATURE": "..."
  },
  "body": {
    "message": "success"
  }
}
响应描述
success已成功接收并处理
failed处理失败；Waffo 将重试
unknown状态未知；Waffo 将重试

​
配置方式

在创建订单/订阅时，通过参数指定回调 URL：

​
本地开发

使用内网穿透工具将本地端口暴露为公网 URL： 
# cloudflared
cloudflared tunnel --url http://localhost:3000

# ngrok
ngrok http 3000