> ## 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 端点、订阅事件类型、查看事件投递记录，并发送测试事件、轮换签名密钥、重新触发失败事件。

## 这是什么

这是商户后台「**开发者**」模块下的「**Webhook**」页面（左侧导航「开发者」→「Webhook 回调」，页面副标题「在 UQPAY 上发生事件时实时接收通知」）。Webhook 让平台在发生事件（如收款成功、放款完成、卡片创建等）时，实时把通知推送到你配置的端点地址。你在这里添加/编辑/删除 Webhook 端点、选择要订阅哪些事件、查看每条通知的投递记录与结果，并可发送测试事件、轮换签名密钥、对失败的事件重新触发。页面标题区（副标题旁）有「**接口文档**」链接可跳转到开发者文档，右上角是「**添加 Webhook**」按钮。想接入回调通知、排查「收不到通知」、或看某条事件推送成功没有时，都从这里进。

页面分两个标签：「**摘要**」看已配置的 Webhook 端点列表，「**事件**」看所有事件的投递记录。

## 操作步骤

进入页面：

1. 左侧导航点击「**开发者**」→「**Webhook 回调**」。
2. 默认停在「**摘要**」标签，展示名下已配置的 Webhook 端点；切到「**事件**」标签看事件投递记录。

添加 Webhook：点右上角「**添加 Webhook**」进入配置页，填写端点 URL 并勾选要订阅的事件。完整步骤见\*\*「新建 Webhook」页\*\*。

管理某个 Webhook（在「摘要」标签，把鼠标移到某行，点行末「**⋯**」菜单）：

1. 「**编辑 Webhook**」——修改该端点的地址或订阅的事件（见下）。
2. 「**发送测试事件**」——向该端点发一条测试通知，投递结果会出现在「事件」标签里。
3. 「**轮换密钥**」——重新生成签名密钥（见下）。
4. 「**删除 Webhook**」——删除该端点，弹窗二次确认，删除后无法撤销。

编辑 Webhook：点「编辑 Webhook」进入全屏编辑页。可改「**端点 URL**」和订阅的事件；「**签名算法**」（HMAC-SHA512）和「**版本**」固定不可改。改完点「**保存更改**」。

轮换签名密钥（签名密钥用于校验收到的通知确实来自 UQPAY）：

1. 在「摘要」该 Webhook 行「**⋯**」菜单点「**轮换密钥**」。
2. 弹窗提示「将立即生成新的签名密钥，当前密钥随即失效」，确认后点「**轮换密钥**」。
3. 新密钥会弹窗**一次性展示**（可点眼睛图标显示明文、点复制按钮复制）。**此密钥仅显示一次，关闭弹窗后无法再次查看**，请立即复制并更新到你的接收端。
4. 保存好后点「**完成，我已保存密钥**」关闭。

> 轮换后旧密钥立即失效，务必先用新密钥更新接收端的验签逻辑，否则会导致后续通知验签失败。

在「事件」标签查看投递记录：

1. 列表展示所有 Webhook 的事件投递记录。
2. 用工具栏筛选：「**按状态筛选**」（所有状态/成功/失败/待处理），以及按「**事件名称**」「**事件类型**」「**源 ID**」「**事件 ID**」搜索，或用时间范围选择器按日期筛（可查最近 90 天内）。
3. 已生效的筛选在下方以标签显示，点标签「×」移除单项，或点「**全部清除**」清空。

查看单条事件详情并重试：

1. 点某行末「**⋯**」→「**查看详情**」，右侧滑出「**事件详情**」面板。
2. 面板展示事件状态、HTTP 状态、尝试次数、事件名称/类型/ID、Webhook 地址、（失败时的）HTTP 错误，以及完整的请求载荷（可复制）。
3. 在详情面板右上角点「**重新触发**」可重发该事件；通常用于投递失败的事件。

## 字段与状态含义

**「摘要」标签列表列：**

| 列      | 含义（商户视角）                          |
| ------ | --------------------------------- |
| 通知 URL | 接收通知的端点地址                         |
| 版本     | 该 Webhook 的事件版本（如 V1.6.0），创建后不可更改 |
| 已订阅    | 该端点订阅的事件数量（显示「N 个事件」）             |

**「事件」标签列表列：**

| 列     | 含义（商户视角）                                        |
| ----- | ----------------------------------------------- |
| 时间    | 事件产生时间                                          |
| 事件名称  | 事件所属的业务类别名称                                     |
| 事件类型  | 具体事件类型标识（如 acquiring.payment\_intent.succeeded） |
| 尝试次数  | 该事件已投递的尝试次数                                     |
| 源 ID  | 触发该事件的业务对象 ID（行内可点击复制）                          |
| 事件 ID | 该条事件的唯一编号（行内可点击复制）                              |
| 状态    | 该条通知的投递状态，见下                                    |
| 已更新   | 该事件最近更新时间                                       |

**事件投递状态：**

| 状态  | 含义                         |
| --- | -------------------------- |
| 成功  | 通知已成功投递到你的端点               |
| 失败  | 投递失败（鼠标悬停状态徽标可看 HTTP 错误详情） |
| 待处理 | 通知投递处理中                    |

**事件详情面板字段：** 状态、HTTP 状态、尝试次数、时间、事件名称、事件类型、事件 ID、Webhook 地址、HTTP 错误（仅失败时显示）、请求载荷（完整 JSON，可复制）。

**订阅事件的分类：** 添加/编辑 Webhook 时，事件按业务线分组勾选，可逐个选、按组选、按业务线全选，或「订阅所有事件」一次全选。五大类别为（具体显示哪些业务线取决于你账户已开通的产品，未开通的不会出现）：

| 类别                    | 覆盖的事件（举例）                |
| --------------------- | ------------------------ |
| PLATFORM（平台/账户）       | 账户开通、RFI 补件要求等           |
| PAYMENTS（收单）          | 收单支付意图、支付尝试、退款、结算、拒付提醒等  |
| GLOBAL ACCOUNTS（全球账户） | 收款人、虚拟账户、入金、放款、货币兑换等     |
| CARDS（发卡）             | 卡片、持卡人、发卡、卡授权、卡账户出入金/转账等 |
| CRYPTO（稳定币出入金）        | 稳定币账户换汇、充值、转账、提现等        |

> 勾选「**订阅所有事件**」只订阅当前已有的事件类型；未来新增的事件类型不会自动监听，需要时回来重新编辑勾选。

**编辑页固定字段：**

| 字段     | 含义                                         |
| ------ | ------------------------------------------ |
| 签名算法   | 用于给通知签名的算法（HMAC-SHA512），固定不可改              |
| 版本     | 该 Webhook 的事件版本，创建后固定不可改                   |
| 端点 URL | 接收通知的地址，必须是 http\:// 或 https\:// 开头的合法 URL |

## 边界与常见处理

* **「摘要」显示「暂无 Webhook」**：还没配置任何端点，提示「添加 Webhook 以接收实时通知。」，点「添加 Webhook」新建。
* **「事件」显示「暂无事件」**：还没有任何事件投递记录，提示「触发后 Webhook 事件将显示在此处。」；可先「发送测试事件」验证。
* **收不到通知 / 想确认到底发出去没有**：切到「事件」标签，按事件 ID / 源 ID 或状态筛选定位那条事件，点「查看详情」看投递状态、HTTP 状态和 HTTP 错误；失败的可点「重新触发」重发。
* **某条事件投递失败**：详情面板会显示 HTTP 状态与 HTTP 错误信息，据此排查你端点的可用性；修好后可「重新触发」。
* **想验证端点是否配置正确**：在「摘要」该行「⋯」菜单点「发送测试事件」，随后到「事件」标签查看这条测试通知的投递结果。
* **改了 URL 后原来订阅的事件还在吗**：编辑时只改 URL、不动事件勾选，订阅的事件保持不变；保存即生效。
* **查不到较早的事件**：事件按时间筛选只支持最近 90 天范围。
* **看不到「添加 Webhook」/ 行「⋯」菜单 / 「重新触发」按钮**：这些是管理操作，需要 Webhook 写权限；没有权限时只能查看，不能增删改或重试，请联系管理员分配权限。

## 常见问法（Q→A）

* **Q：Webhook 在哪里配置？/ 怎么添加回调地址？** A：左侧「开发者」→「Webhook 回调」→「摘要」标签右上角「添加 Webhook」，填端点 URL 并勾选事件；详见「新建 Webhook」页。
* **Q：怎么修改 Webhook 的地址或订阅的事件？** A：在「摘要」该行「⋯」菜单点「编辑 Webhook」，改端点 URL 或勾选事件后点「保存更改」。
* **Q：我配的 Webhook 收不到通知，怎么排查？** A：切到「事件」标签，按状态/事件 ID/源 ID 筛选定位事件，点「查看详情」看投递状态和 HTTP 错误；失败的可「重新触发」重发。
* **Q：怎么测试 Webhook 通不通？** A：在「摘要」该行「⋯」菜单点「发送测试事件」，再到「事件」标签查看这条测试通知的投递结果。
* **Q：一条事件投递失败了能重发吗？** A：能。在「事件」标签点该行「查看详情」，在详情面板点「重新触发」。
* **Q：事件状态有哪几种？** A：成功、失败、待处理三种；失败时把鼠标移到状态徽标上能看到 HTTP 错误详情。
* **Q：「尝试次数」是什么意思？** A：该事件已经尝试投递到你端点的次数。
* **Q：能订阅哪些事件？** A：按业务线分五类——PLATFORM（平台/账户）、PAYMENTS（收单）、GLOBAL ACCOUNTS（全球账户）、CARDS（发卡）、CRYPTO（稳定币出入金），每类下有若干具体事件类型，可逐个选、按组选或全选；具体显示哪些取决于你账户已开通的产品。
* **Q：「订阅所有事件」会自动包含以后新增的事件吗？** A：不会。它只订阅当前已有的事件类型，将来新增的类型需要你回来重新编辑勾选。
* **Q：签名密钥忘了/泄露了怎么办？** A：在「摘要」该行「⋯」菜单点「轮换密钥」重新生成，新密钥仅显示一次，请立即复制并更新接收端；旧密钥会立即失效。
* **Q：签名密钥能再看一次吗？** A：不能。密钥只在生成时展示一次，关闭弹窗后无法再查看；如需要请轮换生成新密钥。
* **Q：Webhook 用什么签名算法？** A：HMAC-SHA512，编辑页可见，固定不可更改。
* **Q：能改 Webhook 的版本吗？** A：不能。版本在创建时确定，编辑页显示为不可修改。
* **Q：只能查多久以前的事件？** A：事件按时间筛选支持最近 90 天范围。
* **Q：为什么我看不到添加/编辑/删除按钮？** A：这些管理操作需要 Webhook 写权限，没有权限时只能查看，请联系管理员分配。
* **Q：删除 Webhook 后还能恢复吗？** A：不能，删除操作无法撤销，会弹窗二次确认。