只订阅您需要的事件
使用POST /v3/webhooks 创建一个端点。仅订阅您集成中真正需要处理的、有文档记录的事件。以下示例订阅 transfer.state_changed。
data.id 保存为 WEBHOOK_ID。打开 GET /v3/webhooks/portal 返回的管理入口,获取该端点的签名密钥,并将其与 API 密钥分开存放在密钥管理系统中。
在解析前先校验
Swipelux 通过 Svix 投递新的 Webhook 集成。请使用您的端点签名密钥与以下请求头,对原始请求体进行校验:svix-idsvix-timestampsvix-signature
先持久化,再确认,最后处理
请在信封的id 上加上唯一性约束。先持久化经过验证的信封,及时返回 2xx,然后再异步处理。
如果事件 ID 已经存在,请仅确认投递,不要重复执行已经完成的副作用。通过您自己的重试队列继续处理挂起或失败的本地任务。切勿将信封的 attempt 字段用作去重键或传输层的重试计数器。
重新获取当前状态
Webhook 的顺序并不是资源历史的权威依据。请使用resource.type 和 resource.id 定位对象,并在更新您的系统之前先获取其当前状态。
对于转账事件,请调用 GET /v3/transfers/{transferId}:
恢复投递
使用GET /v3/webhooks/portal 打开投递日志、重试失败的投递,或者启动一次人工重放。
每次重放都必须经过同样的签名校验和持久化的收件箱。当服务中断后,请重放受影响的时间窗口,并重新获取每个引用的资源。已完成的事件 ID 仍然视为无操作;未完成的记录会异步继续处理。
接下来,请在沙盒中验证重复与乱序投递,然后完成上线清单。