跳转到主要内容

​
这是什么

这是商户后台「开发者」模块下的「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. 在详情面板右上角点「重新触发」可重发该事件；通常用于投递失败的事件。

​
字段与状态含义

「摘要」标签列表列： 「事件」标签列表列： 事件投递状态： 事件详情面板字段： 状态、HTTP 状态、尝试次数、时间、事件名称、事件类型、事件 ID、Webhook 地址、HTTP 错误（仅失败时显示）、请求载荷（完整 JSON，可复制）。 订阅事件的分类： 添加/编辑 Webhook 时，事件按业务线分组勾选，可逐个选、按组选、按业务线全选，或「订阅所有事件」一次全选。五大类别为（具体显示哪些业务线取决于你账户已开通的产品，未开通的不会出现）：
勾选「订阅所有事件」只订阅当前已有的事件类型；未来新增的事件类型不会自动监听，需要时回来重新编辑勾选。
编辑页固定字段：

​
边界与常见处理

  • 「摘要」显示「暂无 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：不能，删除操作无法撤销，会弹窗二次确认。