Webhook 配置

完成后端代码集成后，您需要在 GStable 商户后台配置接收地址，以便平台能够将支付结果推送给您的服务器。

配置接收端点

商户后台支持配置多达 10 个独立的 Webhook 端点。您可以根据环境（开发/生产）或业务模块将事件分发到不同的 URL。

添加步骤

登录商户后台，进入 “Webhook” 页面。
点击 “+ Add Endpoint”。
填写配置信息：
- Endpoint URL：您的服务器用于接收 POST 请求的接口地址（例如 https://api.yoursite.com/webhook/gstable）。必须以 https:// 开头。
- Subscribe Events：根据需要勾选您关注的事件类型。通常，订阅 session.paid 和 session.completed 就足够了。

获取签名密钥

为了确保安全性，GStable 为每个 Webhook 端点分配一个独立的密钥，用于生成请求签名。

在 Webhook 列表中点击您刚刚创建的端点。
在详情区域底部的 验证签名key 区域，点击显式小图标。
您将看到一个以 wkk_ 开头的字符串。
- 注意：请妥善保管此密钥，切勿将其暴露在前端代码中。

安全验证机制

当您的服务器收到请求时，必须执行签名验证，以防止中间人攻击或伪造请求。

验证原理

GStable 请求头包含以下关键字段：

x-gstable-timestamp：请求发送的时间戳。
x-gstable-signature：基于 HMAC-SHA256 算法生成的签名。

签名构造规则：

SignedPayload = Timestamp + ":" + RawBody

快速验证示例 (Node.js)

以下是一个简化的验证函数。关于更详细的实现，请参考 API 文档。

const crypto = require('crypto');

// 从 Dashboard 获取的以 wkk_ 开头的密钥
const WEBHOOK_SECRET = 'wkk_...';

function verifySignature(req) {
  const signature = req.headers['x-gstable-signature'];
  const timestamp = req.headers['x-gstable-timestamp'];
  const rawBody = JSON.stringify(req.body); // 生产环境中建议获取原始 Buffer

  // 1. 构造待签名字符串
  const payload = `${timestamp}:${rawBody}`;

  // 2. 计算签名
  const expectedSignature = crypto
    .createHmac('sha256', WEBHOOK_SECRET)
    .update(payload)
    .digest('hex');

  // 3. 比对
  if (signature === expectedSignature) {
    return true;
  }
  return false;
}

深入了解

关于详细的验证步骤、重放攻击预防以及完整的代码实现，请查阅 API 参考：验证与处理。

重试策略

如果您的服务器未能正确响应（即返回的状态码不是 2xx），或者请求超时（超过 10 秒），GStable 将认为投递失败。

系统会自动执行重试机制：

策略：指数退避 (Exponential Backoff)。
频率：重试间隔将逐渐延长（例如 1 分钟、5 分钟、30 分钟...）。
时长：系统将在 24 小时内持续尝试；如果仍然失败，将停止推送该事件。

避免超时

请确保您的 Webhook 处理逻辑尽可能快。如果业务逻辑（如发货、数据库操作）耗时较长，建议先返回 200 OK，然后在后台异步处理业务。

Webhook 事件列表 →

配置接收端点​

添加步骤​

获取签名密钥​

安全验证机制​

验证原理​

快速验证示例 (Node.js)​

重试策略​