用途
flutterwave-webhooks 用于在服务端安全地接收和处理 Flutterwave 支付平台推送的 Webhook 事件。其目标可概括为三点:签名验证、幂等处理、异步安全处理。该技能适合需要对接 Flutterwave 支付回调、并希望保证事件处理可靠性的开发场景。
主要能力
- 提供 TypeScript 实现模式,包含 v3 与 v4 两个 API 版本的基础地址配置(FLW_V3_BASE_URL、FLW_V4_BASE_URL)与密钥读取(FLW_SECRET_KEY)。
- 定义统一的响应类型 FlwResponse 与错误类型 FlutterwaveApiError,并封装 flwRequest 请求函数,自动附加 Content-Type 与 Authorization 头,并在响应失败或 status 为 error 时抛出错误。
- 提供端点操作参考表,涵盖:v3 的 POST Webhook 回调(接收事件)、v4 的 HMAC-SHA256 签名验证(校验 flutterwave-signature 请求头)、v4 的 GET /charges/{id}(重新核验关键字段)。
- 提供国家/通道矩阵,说明所有市场均建议采用 Webhook 加轮询回退、幂等消费者、60 秒响应 SLA。
- 提供可靠性检查清单,指导服务端二次核验、对账标识存储、幂等与快速响应、版本类型隔离。
使用方式
资料给出的实现模式为 TypeScript。核心步骤包括:配置环境变量 FLW_V3_BASE_URL、FLW_V4_BASE_URL、FLW_SECRET_KEY;使用 getBaseUrl 根据版本选择基础地址;通过 flwRequest 发起请求,该函数会检查密钥是否存在、拼接 URL、附加请求头、解析 JSON 响应,并在失败时抛出 FlutterwaveApiError。
使用示例展示了调用 v4 的 /charges/{id} 接口进行 GET 请求:
export async function runFlutterwaveWebhooksExample() {
return flwRequest<unknown>("v4", "/charges/{id}", {
method: "GET",
});
}
端点参考表如下:
| 版本 | 方法 | 路由 / 操作 | 用途 | 参考 |
|---|---|---|---|---|
| v3 | POST | Webhook 回调 | 接收事件 | https://developer.flutterwave.com/docs/webhooks |
| v4 | DOC | HMAC-SHA256 签名 | 验证 flutterwave-signature 请求头 | https://developer.flutterwave.com/docs/webhooks#verifying-webhook-signatures |
| v4 | GET | /charges/{id} | 重新核验关键字段 | https://developer.flutterwave.com/reference/charges_get |
适用场景
- 需要接收 Flutterwave 支付事件并触发后续业务逻辑(如订单履约)的服务端应用。
- 需要处理异步支付通道、并希望具备重试安全性的集成场景。
- 需要按 webhook id 或事件状态去重、保证消费者幂等的系统。
- 需要在履约前对成功支付状态进行服务端二次核验的支付流程。
限制与注意事项
- 资料未提供具体的安装命令、依赖包名称或完整的 Webhook 接收端实现代码,仅给出请求封装与示例调用。
- 资料未说明收费、价格或平台支持范围等商业信息。
- 可靠性检查清单要求:在履约前服务端重新核验成功支付状态;存储提供方 id、内部 id、tx_ref 和事件 id 以便对账;保持 Webhook 消费者幂等并快速返回 HTTP 200;按版本隔离请求/响应类型以避免 schema 混淆。
- v4 在公开参考中是资源中心化的,建议在代码中按版本维护路由映射与载荷类型,以保证集成准确性。
- 国家/通道矩阵指出所有市场均建议 Webhook 加轮询回退、幂等消费者、60 秒响应 SLA(快速返回 200,将重活延后处理)。