Webhook 投递排查指南

Documentation Index

Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/llms.txt

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

​

概览

本指南帮助你排查客户报告未收到预期 Webhook 的场景。

​

快速参考流程图

​

分步排查流程

​

步骤 1：确认 Webhook 订阅

这是第一步，也是最关键的一步。 在进一步排查前，请先确认你已经订阅了所期望接收的 Webhook 事件类型。如果未订阅某事件类型，UQPAY 就不会发送对应的 Webhook 通知。 如何检查 Webhook 订阅：

1. 登录 UQPAY 控制台
2. 依次进入 Settings → Developer → Webhooks → Summary
3. 确认期望的 Webhook 事件类型已订阅
4. 确认 Webhook 通知 URL 配置正确

详细操作参见 Webhook 设置文档。 如果未订阅：

• 在控制台订阅所需的 Webhook 事件类型
• 配置 Webhook 端点 URL
• 重要： 订阅成功后，UQPAY 只会为订阅激活之后发生的事件发送 Webhook。订阅前已经发生的事件无法追溯补发。

如果已订阅： 请继续进行步骤 2。

​

步骤 2：查看控制台的 Webhook 日志

进入控制台的 Webhook Logs 页面，确认是否有期望 Webhook 的记录。 如何访问 Webhook 日志：

1. 登录 UQPAY 控制台
2. 依次进入 Settings → Developer → Webhooks → Events
3. 可按以下条件筛选：
   • 事件类型
   • 时间范围
   • 状态
   • Reference ID

​

步骤 3：分析结果

​

场景 A：找到 Webhook 记录

如果日志中存在该 Webhook 记录，说明 UQPAY 已成功将 Webhook 发送到你的端点。 检查响应状态码：

​

场景 B：未找到 Webhook 记录

如果日志中不存在该 Webhook 记录，说明 UQPAY 未发送此 Webhook。 需采取的动作： 按下文信息收集小节中的要求，联系 UQPAY 技术支持。

​

客户端排查

如果 Webhook 已发送但返回了非 200 状态码，请按以下步骤排查：

​

1. 检查 IP 白名单

确认你已将 UQPAY 的 Webhook 服务器 IP 地址加入防火墙或安全组白名单。

​

2. 验证 Webhook 端点可用性

• 端点可访问性： 确认你的 Webhook 端点公网可访问
• 近期 SSL 证书变更： 检查是否最近续期或替换过服务器证书
• 网络连通性： 检查是否存在阻碍 UQPAY 触达你端点的网络问题

​

3. 审查 Webhook 端点逻辑

检查你的 Webhook 处理程序实现：

• 请求解析： 确认请求体解析正确
• 错误处理： 检查异常是否被正确捕获与处理
• 响应格式： 确认端点返回 HTTP 200 以及合法的响应体

​

4. 重新触发 Webhook

你可以在控制台重新触发某次 Webhook 进行重发。这有助于验证端点的修复是否已经生效。 如何重新触发 Webhook：

1. 依次进入 Settings → Developer → Webhooks → Events
2. 找到失败的 Webhook 记录
3. 点击 Re-trigger 重新发送该 Webhook

详细操作参见 Webhook 设置文档。

​

联系 UQPAY 支持所需的信息

如果控制台未找到 Webhook 记录，说明 UQPAY 未发送此 Webhook。为便于我们的技术团队排查，请提供以下关键信息：

​

必要信息