> ## Documentation Index
> Fetch the complete documentation index at: https://developers.uqpay.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Webhook 投递排查指南
> 诊断并解决端点未能收到预期 Webhook 事件的问题。
概览
本指南帮助你排查客户报告未收到预期 Webhook 的场景。
快速参考流程图
```mermaid theme={null}
flowchart TD
A[客户报告 Webhook 丢失] --> B{检查 Webhook 订阅}
B -->|未订阅| C[未订阅 Webhook
UQPAY 不会发送]
B -->|已订阅| D[查看控制台的 Webhook 日志]
D --> E{是否有 Webhook 记录?}
E -->|有| F[Webhook 已发送]
E -->|无| G[Webhook 未发送]
F --> H{响应状态码?}
H -->|200 OK| I[Webhook 成功接收并处理]
H -->|非 200| J[客户端问题]
J --> K[检查 IP 白名单]
J --> L[检查端点可用性]
J --> M[检查 SSL 证书变更]
J --> N[检查 Webhook 端点逻辑]
J --> O[如有需要, 重新触发 Webhook]
G --> P[联系 UQPAY 技术支持]
P --> Q[提供必要信息]
I --> R[Webhook 已正确处理
检查客户端应用日志]
C --> S[订阅该 Webhook 事件类型]
style I fill:#90EE90
style J fill:#FFB6C1
style G fill:#FFD700
style P fill:#FFD700
style C fill:#FFA500
style S fill:#87CEEB
```
分步排查流程
步骤 1：确认 Webhook 订阅
**这是第一步，也是最关键的一步。**
在进一步排查前，请先确认你已经订阅了所期望接收的 Webhook 事件类型。如果未订阅某事件类型，UQPAY 就不会发送对应的 Webhook 通知。
**如何检查 Webhook 订阅：**
1. 登录 UQPAY 控制台
2. 依次进入 **Settings** → **Developer** → **Webhooks** → **Summary**
3. 确认期望的 Webhook 事件类型已订阅
4. 确认 Webhook 通知 URL 配置正确
详细操作参见 [Webhook 设置文档](/zh/account-center/v1.6/guide/webhooks-setting)。
**如果未订阅：**
* 在控制台订阅所需的 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 发送到你的端点。
**检查响应状态码：**
| 状态码 | 含义 | 需采取的动作 |
| ---------- | -------------------------------------------------------- | -------------------------------------------- |
| **200 OK** | 响应码 200 表示你的端点已成功接收并处理该 Webhook。UQPAY 认为此次投递已完成，不会重试。 | Webhook 投递正确。请检查应用日志，确认 Webhook 数据是否按预期完成处理。 |
| **非 200** | 非 200 响应表示你的端点未正确处理该 Webhook。UQPAY 会触发重试机制，按特定的重试排期重新发送。 | 请继续进行下文的**客户端排查**。 |
场景 B：未找到 Webhook 记录
如果日志中不存在该 Webhook 记录，说明 UQPAY 未发送此 Webhook。
**需采取的动作：** 按下文**信息收集**小节中的要求，联系 UQPAY 技术支持。
客户端排查
如果 Webhook 已发送但返回了非 200 状态码，请按以下步骤排查：
1. 检查 IP 白名单
确认你已将 [UQPAY 的 Webhook 服务器 IP 地址](/zh/account-center/v1.6/guide/webhooks-overview)加入防火墙或安全组白名单。
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 设置文档](/zh/account-center/v1.6/guide/webhooks-setting)。
如果控制台未找到 Webhook 记录，说明 UQPAY 未发送此 Webhook。为便于我们的技术团队排查，请提供以下关键信息：
| 字段 | 说明 | 示例 |
| ---------------- | ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- |
| **Webhook 事件类型** | 未收到的具体 Webhook 事件类型 | `beneficiary.successful`、`card.create.succeeded`、`acquiring.payment_intent.created` 等 |
| **资源 ID** | 本应触发此 Webhook 的资源 ID。请按 Webhook 类型选用对应资源的 ID（例如支付相关 Webhook 使用 Payment Intent ID，出款相关 Webhook 使用 Payout ID） | PaymentIntent ID、Card ID、Payout ID 等 |