Webhook

Stabo 通过 Webhook 把事件通知（如收款成功）主动推送到你的服务器。你无需轮询，即可实时获知账户变动。

通知机制复制锚点链接

• 协议：HTTPS（TLS 1.2+）
• 请求方式：HTTP POST
• 请求地址：在控制台「集成 → Webhooks」配置的 Webhook URL（必须使用 HTTPS）
• 内容类型：application/json
• 签名算法：HMAC-SHA256
• 重试策略：如果响应状态码不是 2xx，Stabo 将进行指数退避重试，最多重试 5 次
• 重试间隔：1 分钟、5 分钟、30 分钟、2 小时、6 小时
• 超时时间：30 秒（建议在 30 秒内返回响应）

最佳实践：收到 Webhook 通知后，建议先返回 2xx 响应，再异步处理业务逻辑，避免处理超时导致重复推送。

请求头复制锚点链接

Stabo 发送的每个 Webhook 请求都包含以下 HTTP Header：

事件对象结构复制锚点链接

{
  "id": "evt_1Mxxx",
  "object": "event",
  "type": "checkout.payment_intent.succeeded",
  "created": 1678888888,
  "data": {
    "object": {}
  }
}

字段说明：

• id: 事件唯一标识符
• object: 固定值 "event"
• type: 事件类型（如 checkout.payment_intent.succeeded）
• created: 事件创建时间戳（秒）
• data.object: 事件数据载荷（根据事件类型不同而变化）

各产品的事件类型和载荷见产品指南，例如 Checkout 的 Webhook 事件。

签名验证复制锚点链接

你必须验证每个请求的签名，确保 Webhook 请求来自 Stabo，而非第三方伪造。

Webhook-Signature 的格式为 t=timestamp,v1=signature。验证步骤：

1. 解析 Header，取出 t（时间戳，秒）和 v1（签名）。
2. 校验时间戳，拒绝过期请求。容差由商户自行决定，下面的示例取 300 秒。
3. 构造待签名字符串：eventId + "." + timestamp + "." + rawBody。eventId 取自 Webhook-Event-Id，rawBody 是未经解析的原始请求体。
4. 用 Webhook 密钥对待签名字符串计算 HMAC-SHA256，结果转为小写十六进制字符串。
5. 常数时间比较期望签名与 v1。

验证代码示例复制锚点链接

# 变量取自请求: EVENT_ID=Webhook-Event-Id, TIMESTAMP=Webhook-Signature 中的 t
# RAW_BODY 是原始请求体，WEBHOOK_SECRET 是 Webhook 密钥
printf '%s' "${EVENT_ID}.${TIMESTAMP}.${RAW_BODY}" \
  | openssl dgst -sha256 -hmac "${WEBHOOK_SECRET}" \
  | sed 's/^.* //'

用固定样本自测复制锚点链接

下面的样本只用于自测，密钥是示例值。用上面的任一实现，传入样本，应得到 true。验证时把当前时间设为 t 前后 300 秒内。

原始请求体（单行，无结尾换行）：

{"id":"evt_1234567890","object":"event","type":"checkout.payment_intent.succeeded","created":1778480710,"data":{"object":{"paymentIntentId":"pi_MNOL0POUV8IDPXCD","status":"COMPLETED","amount":"20.00","currency":"USD","note":"测试 UTF-8"}}}

改动请求体中的任何一个字符，或把 v1 改成大写，验证都应返回 false。