Webhooks
Webhook 允许 SlaunchX 在事件发生时主动向您的服务器推送通知，无需轮询 API 来获取状态变化。当转账完成、钱包创建、支付结算等事件发生时，SlaunchX 会向您注册的端点发送 HTTP POST 请求，携带描述事件的 JSON 负载。
Webhook 特别适用于：
- 异步工作流 -- 无需轮询即可响应转账完成等事件。
- 实时仪表盘 -- 即时更新余额和状态。
- 审计日志 -- 按发生顺序记录每一个事件。
配置 Webhook
通过 API 注册
发送 POST 请求注册一个 Webhook 端点：
通过控制台注册
- 进入工作空间控制台，导航到 设置 > Webhooks。
- 点击 添加端点。
- 输入您的 HTTPS 端点 URL。
- 选择要订阅的事件类型。
- 保存。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 | 事件时间戳，毫秒级 Unix 纪元时间。 |
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 字段进行去重：
- 收到事件时，检查是否已处理过该
id的事件。 - 如果是，返回
200并跳过处理。 - 如果否，处理事件并记录该
id。
使用消息队列
对于高吞吐量的集成，将收到的事件写入消息队列（如 RabbitMQ、SQS、Redis Streams），然后由独立的消费者处理。这将接收与处理解耦，确保始终能在超时时间内响应。
先验证再处理
在处理负载之前务必验证 Webhook 签名。即使请求看似来自已知 IP，也不要在未验证的情况下信任 Webhook 请求的内容。
监控投递状态
定期检查控制台中的 Webhook 投递日志。投递失败可能表明端点宕机、证书问题或网络故障，需要及时排查。
测试
沙盒环境
沙盒环境支持完整的 Webhook 功能。在上线前使用沙盒测试您的集成：
- 创建沙盒 Webhook -- 注册您的开发端点（沙盒允许使用 HTTP）。
- 触发测试事件 -- 使用沙盒 API 创建转账、钱包等操作。这些操作会向您的端点发送真实的 Webhook 投递。
- 查看投递记录 -- 在沙盒控制台中查看负载、响应码和耗时等信息。
发送测试事件
您可以从控制台发送测试事件，验证端点是否可达并能正确处理：
- 进入 设置 > Webhooks。
- 点击要测试的端点。
- 点击 发送测试事件。
- 选择事件类型。
- SlaunchX 向您的端点发送示例负载并显示响应结果。
本地开发
进行本地开发时，使用隧道服务将本地服务器暴露到公网：
重放事件
如果需要重新处理某个事件（例如修复了处理逻辑中的 bug 后），可以在控制台中重放特定的投递。每次重放都会使用原始负载生成新的投递尝试。