跳转到主要内容

​
这是什么

这是商户后台「开发者 > 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 已成功更新」后返回列表。编辑保存不会重新生成密钥。

​
字段与状态含义

表单字段： 事件业务线（顶层分组）——具体显示哪些业务线，取决于你账户已开通的产品；未开通的业务线不会出现，平台类事件始终可见：
每个业务线、事件组旁会标注「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。
  • 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：只有你账户已开通的产品对应的业务线才会出现，未开通的不显示，需要可联系客户经理开通。