Webhook 概述
每当收款状态发生变更，A55 会向您的 webhook_url 发送 HTTP POST 请求，让您实时掌握支付动态。
为什么使用 Webhook
| 方面 | Webhook（推送） | 轮询（拉取） |
|---|---|---|
| 延迟 | 秒级 | 取决于轮询间隔（分钟级） |
| 可靠性 | 有重试机制的保证投递 | 间隔期间可能遗漏事件 |
| 服务器负载 | 事件驱动，极低 | 无论是否有活动都持续请求 |
配置方式
在收款请求中设置 webhook_url，或在 A55 控制台配置默认 URL。
| 配置 | 说明 |
|---|---|
收款请求中的 webhook_url | 仅接收该笔收款的事件 |
| 控制台中的默认 URL | 当请求中未提供 webhook_url 时使用 |
| 属性 | 值 |
|---|---|
| 方法 | POST |
| Content-Type | application/json |
| 超时 | 30 秒 |
| TLS | 仅 HTTPS |
重试策略
投递失败后将在 24 小时内以指数退避方式重试：
| 次数 | 延迟 | 累计时间 |
|---|---|---|
| 1 | 立即 | T+0 |
| 2 | 1 分钟 | T+1m |
| 3 | 5 分钟 | T+6m |
| 4 | 30 分钟 | T+36m |
| 5 | 2 小时 | T+2h 36m |
| 6 | 6 小时 | T+8h 36m |
| 7 | 24 小时 | T+32h 36m |
经过 7 次失败尝试后，事件在控制台中标记为失败。
| 响应 | 是否重试？ |
|---|---|
2xx | 否 — 投递成功 |
4xx | 否 — 永久性客户端错误 |
5xx | 是 — 服务端暂时性错误 |
| 超时（>30 秒） | 是 |
| 连接被拒绝 | 是 |
幂等处理
Webhook 使用至少一次投递机制。同一事件可能多次到达。您的处理器必须保证幂等性——以 charge_uuid 去重。
快速响应
收到 Webhook 后立即返回 200 OK。将事件处理逻辑放入后台任务，避免超时和重复投递。
测试
| 工具 | 用途 |
|---|---|
| webhook.site | 无需运行服务器即可查看载荷 |
| ngrok | 将本地服务器暴露给沙箱 Webhook |
| A55 沙箱 | 在沙箱环境发送真实测试事件 |