跳到主要内容

Webhook 管理

Webhook 是 GStable 向你的后端系统实时推送事件通知（如支付成功、结算完成）的机制。通过 Webhook API，你可以通过程序化方式管理你的接收端点。

限制说明

为了保证推送质量，每个账户最多允许创建 10 个 Webhook 端点。

Webhook 对象​

核心属性​

属性类型描述
webhookIdStringWebhook 的唯一标识符（如 wkid_DDr1EN...）。
webhookNameString用于识别该端点的名称。
webhookUrlString接收 POST 请求的 HTTPS URL。
statusString当前状态。见下文状态定义。
subscribedEventsArray订阅的事件类型列表（如 session.paid）。
keyString签名密钥。用于验证回调通知的合法性。

状态定义 (Status)​

状态标识符描述
活跃active正常状态。平台会向该端点发送通知。
已禁用inactive用户手动禁用。平台停止发送通知。
已暂停paused系统自动暂停。当平台向该 URL 发送通知连续多次失败（如 500 错误或超时）后，会自动将状态置为 paused。你需要修复服务器问题后，手动将其恢复为 active。

创建 Webhook​

POST /webhook/create

创建一个新的接收端点。创建成功后，系统会生成一个唯一的签名密钥 (key)，请妥善保存。

请求参数​

参数类型必填描述
webhookNameString✅名称（最大 100 字符）。
webhookUrlString✅回调 URL（最大 1000 字符）。必须是 HTTPS。
subscribedEventsString[]✅订阅的事件列表。
webhookDescriptionString❌描述信息（最大 1000 字符）。

请求示例​

{
  "webhookName": "生产环境接收端",
  "webhookUrl": "https://api.yoursite.com/webhooks/gstable",
  "webhookDescription": "用于接收支付完成和结算完成事件",
  "subscribedEvents": [
    "session.paid",
    "session.completed"
  ]
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
    "webhookName": "生产环境接收端",
    "webhookDescription": "用于接收支付完成和结算完成事件",
    "webhookUrl": "https://api.yoursite.com/webhooks/gstable",
    "subscribedEvents": [
      "session.paid",
      "session.completed"
    ],
    "key": "wkk_example_secret_key_000",
    "createAt": "2026-01-03 08:36:03",
    "updateAt": "2026-01-03 08:36:03",
    "status": "active"
  }
}

更新 Webhook​

POST /webhook/update

全量更新

更新接口采用全量替换策略。调用此接口时，必须传递 Webhook 的所有字段（包括那些不想修改的字段）。

请求示例​

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
  "webhookName": "生产环境接收端 (已更新)",
  "webhookUrl": "https://api.yoursite.com/webhooks/gstable_v2",
  "webhookDescription": "更新了回调地址",
  "subscribedEvents": [
    "session.paid"
  ]
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

获取 Webhook 列表​

GET /webhook/list

由于平台限制每个账户最多创建 10 个 Webhook，此接口返回全量列表，不提供分页。

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "webhooks": [
      {
        "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
        "webhookName": "测试webhook",
        "webhookUrl": "https://webhook.example.com/gstable",
        "status": "active",
        "key": "wkk_example_secret_key_000",
        ...
      }
    ]
  }
}

获取 Webhook 详情​

GET /webhook/detail/:webhookId

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "webhookId": "wkid_DDr1ENAGmHjPy3Oq",
    "webhookName": "测试Webhook-更新",
    "webhookDescription": "用于接收支付完成和结算完成事件",
    "webhookUrl": "https://www.google.com",
    "subscribedEvents": [
      "session.paid"
    ],
    "key": "wkk_example_secret_key_000",
    "createAt": "2026-01-03 08:36:03",
    "updateAt": "2026-01-03 09:10:05",
    "status": "active"
  }
}

状态管理​

你可以手动禁用或启用 Webhook。如果 Webhook 因多次投递失败进入 paused 状态，也需要通过“启用”接口将其恢复。

禁用 (Disable)​

POST /webhook/disable

启用 (Enable)​

POST /webhook/enable

请求示例​

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

密钥管理​

刷新密钥 (Rotate Key)​

POST /webhook/key/refresh

如果你怀疑签名密钥 (key) 已泄露，可以调用此接口生成一个新的密钥。 注意： 刷新密钥后，旧密钥将立即失效。请务必同步更新你的后端验证逻辑，否则将导致验签失败。

请求示例​

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}

删除 Webhook​

POST /webhook/remove

永久删除一个 Webhook 端点。

请求示例​

{
  "webhookId": "wkid_DDr1ENAGmHjPy3Oq"
}

响应示例​

{
  "code": 0,
  "message": "success",
  "data": {
    "success": true
  }
}