> ## 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 全屏表单，填写接收通知的端点 URL、勾选要订阅的事件后创建 webhook，创建成功会一次性显示用于验签的签名密钥。

## 这是什么

这是商户后台「**开发者 > Webhook 回调**」下的**新建 Webhook** 全屏表单（页面标题「添加 Webhook」，副标题「输入您的端点 URL 并选择要订阅的事件」）。从「Webhook 回调」列表页「摘要」标签右上角点「**添加 Webhook**」进入。你在这里填写一个用于接收 UQPAY 事件通知的端点 URL、勾选想订阅的事件，创建后系统会实时把这些事件推送到该 URL。**编辑已有 Webhook** 用的是同一套全屏表单（标题「编辑 Webhook」），从列表行的「⋯」菜单选「编辑 Webhook」进入，可改端点 URL 和订阅的事件。想开始接收支付、账户、发卡等事件的实时回调通知时，从这里配置。

> 新建/编辑 Webhook 需要相应操作权限，没权限时列表上看不到「添加 Webhook」按钮、行菜单里也没有编辑入口。页面右上角「✕」直接关闭返回列表，未提交的内容不保存。

## 操作步骤

新建一个 Webhook：

1. 进入「**开发者 > Webhook 回调**」页，在「**摘要**」标签右上角点击「**添加 Webhook**」，进入全屏表单。
2. 确认「**签名算法**」与「**版本**」——这两项已预置好、不可修改（签名算法固定为 HMAC-SHA512，版本固定为当前版本 V1.6.0）。
3. 在「**端点 URL**」填写你用来接收通知的地址，必须是以 `http://` 或 `https://` 开头的完整合法网址（例如 `https://your-domain.com/webhooks`）。
4. 在下方「**事件**」区勾选要订阅的事件：
   * 事件按「业务线 → 事件组 → 具体事件」三层展开，点每一行右侧的展开箭头（▾）展开/收起；行左侧是勾选框，用来勾选该业务线/事件组。
   * 想订阅全部，勾选顶部「**订阅所有事件**」；也可以只勾某个业务线、某个事件组，或逐个勾具体事件（父级会显示全选/半选状态）。
   * 勾选后右侧「**示例载荷**」会实时预览所选事件的示例通知内容，可点右上角复制按钮复制。
   * 底部会显示已选事件数量。
5. 核对无误后点右下角「**创建**」。
6. 创建成功后，页面会显示一次性的**签名密钥**面板（「Webhook 已创建」）：点眼睛图标可显示/隐藏完整密钥，点复制按钮复制。**这个密钥只显示这一次**，请立即复制保存——用它来验证收到的 Webhook 签名。保存好后点「**完成，我已保存密钥**」返回列表。

编辑一个已有 Webhook：

1. 在「Webhook 回调」列表「摘要」标签，把鼠标移到目标行、点行末「**⋯**」菜单 →「**编辑 Webhook**」。
2. 表单会预填该 Webhook 当前的端点 URL 和已订阅事件（签名算法、版本沿用原值、不可改）。
3. 按需修改端点 URL 或增减订阅事件。
4. 点右下角「**保存更改**」，提示「Webhook 已成功更新」后返回列表。编辑保存**不会**重新生成密钥。

## 字段与状态含义

**表单字段：**

| 字段     | 含义（商户视角）                            | 备注                                 |
| ------ | ----------------------------------- | ---------------------------------- |
| 签名算法   | 用于给 Webhook 通知签名的算法，固定为 HMAC-SHA512 | 预置，不可修改                            |
| 版本     | 事件与载荷所用的接口版本，固定为 V1.6.0             | 预置，不可修改                            |
| 端点 URL | 你用来接收通知的地址，事件发生时 UQPAY 会推送到这里       | 必填，须为 http\:// 或 https\:// 开头的合法网址 |
| 事件     | 你要订阅的事件清单，按业务线分组勾选                  | 至少选一个                              |
| 订阅所有事件 | 一键勾选当前全部事件                          | 勾了它，之后新增的事件类型不会自动订阅，需再来编辑添加        |
| 示例载荷   | 右侧实时预览所勾选事件的示例通知内容                  | 仅供参考，可复制                           |
| 签名密钥   | 创建成功后一次性显示，用于验证收到通知的签名              | 只显示一次，关闭后无法再查看                     |

**事件业务线（顶层分组）**——具体显示哪些业务线，取决于你账户已开通的产品；未开通的业务线不会出现，平台类事件始终可见：

| 业务线（屏上所见）             | 含义              | 包含的事件组（示例）                                                                          |
| --------------------- | --------------- | ----------------------------------------------------------------------------------- |
| PLATFORM（平台/账户）       | 账户开通、资料补充等平台级事件 | ONBOARDING（账户创建/更新）、RFI（需补充资料）                                                      |
| PAYMENTS（收单支付）        | 收单支付相关事件        | ACQUIRING（支付意图、支付尝试、退款、结算、付款、拒付预警等）                                                 |
| GLOBAL ACCOUNTS（全球账户） | 全球账户与资金流转事件     | BENEFICIARY（收款人）、VIRTUAL（虚拟账户）、DEPOSIT（入金）、PAYOUT（付款）、CONVERSION（换汇）、RFI            |
| CARDS（发卡）             | 卡片与卡交易事件        | CARD（卡片创建/更新/状态/充值/提现）、CARDHOLDER（持卡人）、ISSUING（卡交易、结算、拒付、报表等）、CARD AUTH（3DS/OTP/激活） |
| CRYPTO（稳定币出入金）        | 稳定币账户 ramp 事件   | CONVERSION（换汇）、DEPOSIT（充值）、TRANSFER（转账）、WITHDRAW（提现）                                |

> 每个业务线、事件组旁会标注「N events」表示其下事件数量。展开到最底层是一条条具体事件（例如 `onboarding.account.create`、`acquiring.refund.succeeded`），逐条勾选即可。

## 边界与常见处理

* **列表上没有「添加 Webhook」按钮 / 行里没有「编辑 Webhook」**：多为没有 Webhook 写权限，需让管理员分配权限。
* **端点 URL 填了创建不了**：URL 必须以 `http://` 或 `https://` 开头且格式合法，纯域名或缺协议头会被拦下。
* **提示要至少选一个事件**：事件区一个都没勾时无法创建，至少勾选一个事件。
* **想订阅的某个业务线在事件区找不到**：该业务线对应的产品尚未在你账户开通，只有已开通产品的事件才会出现；需要的话联系客户经理开通。
* **勾了「订阅所有事件」后，新上线的事件收不到**：订阅所有事件只覆盖当时已有的事件，之后新增的事件类型不会自动纳入，需再进编辑页补勾。
* **创建后忘了复制签名密钥 / 密钥面板关掉了**：签名密钥只在创建成功时显示一次，关闭后无法再查看；可到列表行「⋯」菜单用「轮换密钥」生成一把新密钥（旧密钥随即失效，记得同步更新你的接收端）。
* **编辑保存后密钥没变**：编辑只更新 URL 和订阅事件，不会重新生成密钥；要换密钥用行菜单的「轮换密钥」。
* **创建/更新失败提示**：会在表单顶部红色横幅显示失败原因，按提示调整后重试。

## 常见问法（Q→A）

* **Q：怎么新建一个 Webhook？** A：「开发者 > Webhook 回调」页「摘要」标签右上角点「添加 Webhook」，填端点 URL、勾选要订阅的事件，点「创建」；成功后立刻复制显示的签名密钥。
* **Q：端点 URL 要填什么？有什么格式要求？** A：填你用来接收通知的地址，必须以 http\:// 或 https\:// 开头且是合法网址，例如 [https://your-domain.com/webhooks。](https://your-domain.com/webhooks。)
* **Q：签名算法和版本能改吗？** A：不能，签名算法固定为 HMAC-SHA512、版本固定为 V1.6.0，都是预置项。
* **Q：可以订阅哪些事件？** A：按业务线分组——PLATFORM（平台/账户）、PAYMENTS（收单支付）、GLOBAL ACCOUNTS（全球账户）、CARDS（发卡）、CRYPTO（稳定币出入金）；具体显示哪些取决于你账户开通的产品。可勾单个事件、整组或整条业务线，也可「订阅所有事件」。
* **Q：「订阅所有事件」勾了以后新增的事件会自动收到吗？** A：不会，它只覆盖当时已有的事件；之后新上线的事件类型要再进编辑页补勾。
* **Q：右边的「示例载荷」是什么？** A：勾选事件后右侧会实时预览这些事件的示例通知内容，供你参考对接，可以复制。
* **Q：创建后显示的密钥是什么？为什么只看到一次？** A：那是用于验证 Webhook 签名的签名密钥，出于安全只在创建成功时显示一次，请立即复制保存；关闭面板后无法再查看。
* **Q：密钥没记下来怎么办？** A：到「Webhook 回调」列表对应行「⋯」菜单点「轮换密钥」生成新密钥，旧密钥会立即失效，记得同步更新接收端。
* **Q：怎么修改已经建好的 Webhook？** A：在列表行「⋯」菜单点「编辑 Webhook」，改端点 URL 或订阅事件后点「保存更改」；编辑不会改变密钥。
* **Q：为什么我建不了 / 看不到添加按钮？** A：通常是没有 Webhook 写权限，请联系管理员分配。
* **Q：为什么某个业务线的事件我这里没有？** A：只有你账户已开通的产品对应的业务线才会出现，未开通的不显示，需要可联系客户经理开通。