用途:Interswitch Webhooks 提供基于回调的实时事件通知,覆盖交易、订阅、支付链接和发票等业务场景。
主要能力:支持多种事件类型,包括 TRANSACTION.CREATED/UPDATED/COMPLETED、SUBSCRIPTION.CREATED/TRANSACTION_SUCCESSFUL/TRANSACTION_FAILURE/CANCELLED、PAYMENT_LINK.CREATED/COMPLETED、INVOICE.CREATED/PAID。回调负载包含 eventType、eventId、ISO 8601 时间戳及 data(如 transactionRef、amount、currency、responseCode、responseDescription、paymentReference、customerEmail 等字段)。
使用方式:在 Quickteller Business 后台配置 webhook:登录后进入 Settings → Webhooks,填写 HTTPS 回调 URL,选择订阅事件类型,并复制 webhook 密钥用于签名校验。每个请求带 X-Interswitch-Signature 头,值为使用密钥对原始请求体做 HmacSHA512 的十六进制摘要。必须用原始请求体(未解析 JSON)校验签名,并使用 timing-safe 比较。示例中给出 Express.js 与 Next.js 处理方式:先用 express.raw({ type: 'application/json' }) 或 request.text() 取原始体,校验失败返回 401,校验通过后立即返回 HTTP 200 空响应,再异步处理事件。
重试策略:非 200 响应最多重试 5 次,采用指数退避;响应要求为 HTTP 200 且无响应体。
最佳实践与限制:应立即返回 200 并异步处理;实现幂等(记录已处理的 eventId);生产环境建议使用任务队列(如 Bull、BullMQ);记录所有事件负载用于调试与审计;对所有事件类型做处理或至少记录;配置失败率或丢事件监控。资料未提供收费、价格或平台支持范围等信息。