Webhook 是 PayMatrix 向商户服务端推送实时事件通知的机制。当支付、退款、争议等关键事件发生时，平台会主动向商户配置的回调地址发送 HTTP POST 请求。
为什么需要 Webhook
- 实时性：支付状态变更后秒级通知，无需轮询
- 可靠性：平台保证至少投递一次，支持失败重试
- 权威性：Webhook 是订单状态变更的权威来源
回调请求格式
HTTP 方法
POST，Content-Type 为 application/json
请求头
| Header | 说明 |
|---|
Content-Type | application/json |
X-Merchant-Id | 商户 ID |
X-Pmp-Event-Id | 事件唯一 ID（如 evt_xxx） |
X-Pmp-Event-Type | 事件类型（如 order.payment.succeeded） |
X-Pmp-Timestamp | Unix 秒级时间戳 |
X-Pmp-Signature | HMAC-SHA256 签名（用于验签） |
请求体结构
{
"event_id": "evt_test_8f2c1d3a5b7e9f01",
"event_type": "order.payment.succeeded",
"timestamp": 1749081600,
"data": {
"order_id": "1000126011700000100001",
"merchant_transaction_id": "ORDER-20260101-001",
"amount": 100.00,
"currency_code": "USD",
"status": 2,
"payment_method": "card",
"paid_at": "2026-01-01T12:30:00Z"
}
}
| 字段 | 类型 | 说明 |
|---|
event_id | String | 事件唯一 ID，用于幂等去重 |
event_type | String | 事件类型 |
timestamp | Long | 事件发生时间（Unix 秒） |
data | Object | 事件负载，内容随事件类型变化 |
配置 Webhook
登录商户门户，进入「开发者设置 → Webhook 管理」：
- 点击「添加 Webhook」
- 填写你的回调 URL（必须 HTTPS）
- 设置签名密钥（用于验签，可自动生成）
- 勾选需要订阅的事件类型
- 保存
建议为沙盒和生产环境分别配置不同的 Webhook URL，便于区分测试与生产事件。
测试 Webhook
配置完 Webhook 后，可以使用「测试发送」功能验证：
- 在 Webhook 列表中选择要测试的 Webhook
- 点击「测试发送」
- 选择事件类型
- 可选填写自定义 Payload
- 点击发送
平台会向你的回调地址发送一条测试通知，你可以查看投递结果。
投递重试机制
- 首次投递失败后，平台会自动重试
- 重试间隔：1min、5min、15min、30min、1h（指数退避）
- 超过最大重试次数后标记为失败
- 可在商户门户查看投递日志和审计记录
商户服务端要求
- 响应时间：请在 10 秒内返回 HTTP 2xx 状态码，否则视为投递失败
- 幂等处理：同一
event_id 可能被重复投递，务必做幂等处理
- 签名验证：收到回调后先验签，确认请求来自 PayMatrix
签名验签
详见 Webhook 签名验签。 