Webhooks

Webhooks 让 SlaunchX 向您的服务器推送实时事件通知，无需轮询 API 来获取状态变更。当某些事件发生时——转账完成、钱包创建、付款结算——SlaunchX 会向您注册的端点发送一个 HTTP POST 请求，其中包含描述事件的 JSON 载荷。

这在以下场景特别有用：

• 异步工作流 -- 无需轮询即可响应转账完成事件。
• 实时仪表盘 -- 即时更新余额和状态。
• 审计追踪 -- 按发生顺序记录每个事件。

---

设置 Webhooks

通过 API

通过发送 POST 请求注册 webhook 端点：

通过管理面板

1. 在您的工作区管理面板中导航到 设置 > Webhooks。
2. 点击 添加端点。
3. 输入您的 HTTPS 端点 URL。
4. 选择您要订阅的事件。
5. 保存。SlaunchX 将为您生成一个签名密钥——请安全存储。

:::caution 需要 HTTPS Webhook 端点必须使用 HTTPS。SlaunchX 不会在生产环境中向纯 HTTP URL 发送事件。在沙箱模式下，允许使用 HTTP URL 进行本地开发。 :::

---

事件类型

以下事件可用于 webhook 订阅：

事件	说明
transfer.created	新的转账订单已创建
transfer.completed	转账已成功执行
transfer.failed	转账执行失败
payment.created	付款已发起
payment.completed	付款已成功结算
payment.failed	付款结算失败
wallet.created	新的钱包账户已创建
wallet.updated	钱包的状态或配置已变更
wallet.frozen	钱包已被管理员冻结

您可以订阅单个事件，或使用 * 接收所有事件。

---

载荷格式

每个 webhook 投递都是一个 HTTP POST 请求，JSON 请求体遵循以下结构：

{
  "id": "evt_8f4a2b3c7d9e",
  "type": "transfer.completed",
  "timestamp": 1709337600000,
  "data": {
    "transferId": "txn_789xyz",
    "sourceWalletId": "w_123",
    "targetWalletId": "w_456",
    "amount": "100.00",
    "currency": "USD",
    "status": "COMPLETED"
  }
}

载荷字段

字段	类型	说明
id	string	唯一事件标识符。用于幂等处理。
type	string	事件类型（参见 事件类型）。
timestamp	long	事件时间戳（毫秒级 epoch）。
data	object	事件特定载荷。结构取决于事件类型。

投递请求头

每个 webhook 请求包含以下 HTTP 请求头：

请求头	说明
Content-Type	始终为 application/json
X-Webhook-Id	与载荷中的 id 字段相同
X-Webhook-Timestamp	请求发送时的 Unix 时间戳（秒）
X-Webhook-Signature	用于验证的 HMAC-SHA256 签名（见下文）
User-Agent	SlaunchX-Webhooks/1.0

---

签名验证

每个 webhook 投递都经过签名，以便您验证其来自 SlaunchX 且未在传输过程中被篡改。签名计算方式为：

signature = hex(HMAC-SHA256(webhookSecret, timestamp + "." + rawBody))

其中：

• webhookSecret 是您在创建 webhook 端点时获得的签名密钥。
• timestamp 是 X-Webhook-Timestamp 请求头中的值。
• rawBody 是原始 HTTP 请求体（不要解析后再重新序列化）。

验证示例

:::caution 始终验证签名 在处理 webhook 载荷之前务必先验证签名。这可以防止伪造的请求。此外，检查时间戳以防止重放攻击——拒绝任何时间戳超过 5 分钟的请求。 :::

---

重试策略

如果您的端点在 5 秒 内没有返回 2xx 状态码，SlaunchX 会认为投递失败，并使用指数退避进行重试：

尝试	失败后延迟
第 1 次重试	1 分钟
第 2 次重试	5 分钟
第 3 次重试	30 分钟
第 4 次重试	2 小时
第 5 次重试	8 小时

经过 5 次重试失败（共 6 次尝试）后，该事件将被标记为失败。您可以从管理面板或通过 API 手动重试失败的投递。

自动禁用

如果您的端点连续 3 天持续失败，SlaunchX 将自动禁用该 webhook 并通过电子邮件通知您的账户管理员。端点恢复健康后，可从管理面板重新启用。

---

最佳实践

快速响应

在 5 秒 内返回 200 OK 响应。将任何耗时处理改为异步执行——先确认接收，然后在后台任务或队列中处理事件。

收到 webhook  -->  验证签名  -->  返回 200  -->  加入处理队列
                                                      |
                                               异步处理事件

幂等地处理事件

Webhook 投递可能会被重试，这意味着您的端点可能多次收到同一个事件。使用 id 字段进行去重：

1. 收到事件时，检查是否已处理过具有该 id 的事件。
2. 如果是，返回 200 并跳过处理。
3. 如果否，处理事件并记录该 id。

使用队列

对于高吞吐量集成，将收到的事件写入消息队列（例如 RabbitMQ、SQS、Redis Streams），然后用单独的 worker 处理。这将接收和处理解耦，确保您始终在超时时间内响应。

处理前先验证

始终在处理载荷之前验证 webhook 签名。即使请求看起来来自已知 IP，也不要在未验证的情况下信任 webhook 请求的内容。

监控投递健康状况

定期检查管理面板中的 webhook 投递日志。失败的投递可能表明端点停机、证书问题或需要关注的网络问题。

---

测试

沙箱环境

沙箱环境支持完整的 webhook 功能。在上线前使用它来测试您的集成：

1. 创建沙箱 webhook -- 注册您的开发端点（沙箱中允许使用 HTTP）。
2. 触发测试事件 -- 使用沙箱 API 创建转账、钱包等。这些操作会向您的端点生成真实的 webhook 投递。
3. 检查投递 -- 在沙箱管理面板中查看投递日志，了解载荷、响应码和时间信息。

发送测试事件

您可以从管理面板发送测试事件，以验证您的端点是否可达并能正确处理：

1. 进入 设置 > Webhooks。
2. 点击要测试的端点。
3. 点击 发送测试事件。
4. 选择事件类型。
5. SlaunchX 向您的端点发送示例载荷并显示响应。

本地开发

对于本地开发，使用隧道服务将您的本地服务器暴露到互联网：

重放事件

如果您需要重新处理某个事件（例如在修复处理程序中的 bug 之后），可以使用管理面板重放特定的投递。每次重放都会使用原始载荷生成一次新的投递尝试。

---

后续步骤

• HMAC 认证 -- 了解如何使用 HMAC-SHA256 签名认证 API 请求。
• 错误处理 -- 了解响应信封格式和错误码。