Webhook 日志与重发

已废弃 / 非集成必需

本页描述的 /api/v1/merchant/webhooks* 属于旧的原生 Merchant API（请求头 HMAC 方案），不是规范的 GodaPay 兼容集成路径的一部分，可能在你的部署中不可用。

规范集成不需要这些端点：平台在收款完成时会自动向你的 returnUrl 投递 webhook，并按退避策略自动重试（1m/5m/15m/1h/6h，共 5 次）。漏收时请用 查询订单（POST /pay/order/query）兜底。webhook 的格式与验签见 Webhooks。

如需按订单人工重发，请联系平台团队。

以下内容仅适用于仍在使用旧原生 API 的存量商户。

列表

GET /api/v1/merchant/webhooks

查询参数

参数	类型	描述
status	string	按状态过滤：pending、success、failed
order_id	string (UUID)	按关联订单 ID 过滤
page	number	页码，默认 1
limit	number	每页条数，默认 20，上限 100

请求

curl -X GET "https://${API_HOST}/api/v1/merchant/webhooks?status=failed&limit=20" \
  -H "X-Merchant-Id: ${MERCHANT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: 1735660800" \
  -H "X-Signature: <computed>"

GET 请求签名时 body 用空字符串。查询参数不参与签名（签名只覆盖 path）。

响应

{
  "success": true,
  "data": {
    "data": [
      {
        "id": "fb1a3c0e-1234-4abc-9def-...",
        "order_id": "0b8a4f32-1c1e-4a1c-9b25-3a9c2e0f7d5b",
        "merchant_order_id": "ORD-001",
        "url": "https://your-server.example/webhook",
        "event": "order.completed",
        "status": "failed",
        "response_code": 502,
        "attempts": 3,
        "max_attempts": 5,
        "next_retry_at": "2026-01-15T11:15:00.000Z",
        "sent_at": "2026-01-15T11:00:00.000Z",
        "created_at": "2026-01-15T10:30:00.000Z"
      }
    ],
    "pagination": {
      "page": 1,
      "limit": 20,
      "total": 137,
      "total_pages": 7
    }
  },
  "meta": { "timestamp": "2026-01-15T11:30:00.000Z" }
}

字段

字段	类型	描述
id	string (UUID)	Webhook 投递记录 ID
order_id	string (UUID)	触发该 webhook 的订单 ID
merchant_order_id	string	你提交的订单 ID（便于对账）
url	string	实际投递的目标 URL
event	string	事件名
status	string	pending / success / failed
response_code	number | null	你的服务器返回的 HTTP 状态码
attempts	number	已尝试次数
max_attempts	number	最大重试次数（默认 5）
next_retry_at	string | null (ISO 8601)	下次自动重试时间，达到上限后为 null
sent_at	string | null (ISO 8601)	最近一次投递时间
created_at	string (ISO 8601)	记录创建时间

单条详情

GET /api/v1/merchant/webhooks/:webhookId

返回额外的 payload（已发送的请求体）和 response_body（你的服务器返回内容），便于排查投递失败原因。

curl -X GET "https://${API_HOST}/api/v1/merchant/webhooks/fb1a3c0e-1234-4abc-9def-..." \
  -H "X-Merchant-Id: ${MERCHANT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: 1735660800" \
  -H "X-Signature: <computed>"

重发

POST /api/v1/merchant/webhooks/:webhookId/resend

立即重新投递一次。重发使用与原始投递相同的签名规则（HMAC over data），便于你在服务器恢复后补收漏掉的事件。

curl -X POST "https://${API_HOST}/api/v1/merchant/webhooks/fb1a3c0e-1234-4abc-9def-.../resend" \
  -H "X-Merchant-Id: ${MERCHANT_ID}" \
  -H "X-API-Key: ${API_KEY}" \
  -H "X-Timestamp: 1735660800" \
  -H "X-Signature: <computed>"

POST 请求 body 为空时，签名时 body 用空字符串 ""。

使用建议

• 服务器宕机后补收：服务器恢复后，调用列表筛选 status=failed，逐一 resend。
• 对账兜底：定期比对你系统中的订单与 webhook 投递记录，对缺失的 order.completed 调用 resend。
• 永远幂等：重发会重新触发你的处理逻辑，确保你按 (order_id, event) 做了去重（详见 Webhooks）。