Webhooks｜ 创建与管理

Webhook 配置流程

1. 进入 Webhooks 管理页面: 前往 开发者 > Webhooks，进入 Webhooks 管理页面。该页面集中展示当前已配置的所有 Webhook 端点，并提供创建、编辑和管理事件推送配置的入口。

2. 新建 Webhook: 点击 创建 Webhook，进入 Webhook 配置页面。

3. 配置 Webhook 基本信息: 填写用于事件推送的基础信息。
   • 端点 URL: 填写一个可接收 Webhook 事件通知的 HTTPS 地址。 该地址需满足以下条件：
     • 可通过公网访问
     • 支持服务器到服务器（server-to-server）请求
     • 由可信的后台系统进行管理
   • 描述（可选）: 填写用于区分该端点用途的说明，例如：
     • 支付结果处理
     • 订阅生命周期同步
     • 内部系统或报表同步 

描述信息仅用于管理和识别，不影响事件推送逻辑。

4. 选择事件订阅范围: 选择该 Webhook 端点需要接收的事件类型。仅被选中的事件才会推送至该端点。
   • 订阅（Subscription）
     • 试用期即将结束
     • 首次订阅扣费
     • 订阅取消
     • 订阅价格变更
   • 发票（Invoice）
     • 发票支付成功
     • 发票支付失败
     • 发票退款
   • 交易（Trade）
     • 交易成功
     • 交易支付失败
   • 退款（Refund）
     • 退款成功
     • 退款失败

事件可按需选择。对于集中处理业务逻辑的系统，可订阅全部事件；对于职责单一的系统，建议仅选择相关事件类型。

5. 创建并启用 Webhook: 点击 创建并激活 保存配置并启用端点。
   • Webhook 端点将立即生效。
   • 系统开始按所选事件类型推送通知。
   • 该端点会显示在 Webhooks 列表中，状态为 激活。

Webhook 管理说明

1. 编辑 Webhook 配置: 在端点操作菜单中选择 编辑，可修改：
   • 端点 URL
   • 描述信息
   • 已订阅的事件类型

保存后，变更将立即生效。

2. 暂停事件推送: 选择 冻结 可暂停该端点的事件推送。
   • 系统不再向该端点发送任何事件
   • 原有配置与事件选择将被保留
   • 后续可随时重新启用，无需重新配置

该操作常用于系统维护、接口迁移或临时排查问题。

Webhooks 列表筛选与查找

1. 按端点 URL 搜索: 在搜索框中输入完整或部分端点 URL，可快速定位对应的 Webhook 配置。

2. 按状态筛选: 使用 状态 筛选器查看：
   • 激活：正在接收事件的端点。
   • 冻结：已暂停事件推送的端点。

3. 重置列表视图: 点击 重置 可清除所有筛选条件，恢复完整 Webhooks 列表。

最佳实践

• 每个 Webhook 端点仅接收配置时选定的事件类型。
• 即使端点处于冻结状态，配置仍可查看和编辑。
• 建议仅向具备相关技术权限的人员开放 Webhook 配置与管理权限。
• 每个 Subotiz 账号最多可创建 10 个 Webhook 端点。