> ## Documentation Index
> Fetch the complete documentation index at: https://developers-sandbox.uqpaytech.com/docs/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<br/>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 已正确处理<br/>检查客户端应用日志]
    
    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. 在侧边栏底部打开 **Developers**，然后选择 **Webhooks** → **Summary**
3. 确认期望的 Webhook 事件类型已订阅
4. 确认 Webhook 通知 URL 配置正确

详细操作参见 [Webhook 设置文档](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-setting.md)。

**如果未订阅：**

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

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

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

进入 Webhooks 页面的 **Events** 标签页，确认是否有期望 Webhook 的记录。

**如何访问 Webhook 日志：**

1. 登录 UQPAY 控制台
2. 在侧边栏底部打开 **Developers**，然后选择 **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 地址](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-overview.md)加入防火墙或安全组白名单。

### 2. 验证 Webhook 端点可用性

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

### 3. 审查 Webhook 端点逻辑

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

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

### 4. 重新触发 Webhook

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

**如何重新触发 Webhook：**

1. 在侧边栏底部打开 **Developers**，然后选择 **Webhooks** → **Events**
2. 打开失败的 Webhook 投递详情
3. 点击 **Re-Trigger** 重新发送该 Webhook

详细操作参见 [Webhook 设置文档](https://developers-sandbox.uqpaytech.com/docs/zh/account-center/v1.6/guide/webhooks-setting.md)。

## 联系 UQPAY 支持所需的信息

如果控制台未找到 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 等 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.