支付可靠性
Pix ↔ 稳定币接入中的 webhook 与幂等性
标识防止重复，webhook 减少等待，查询负责对账。 三者须配合使用。超时不能证明创建失败，webhook 可能重复，旧事件也可能晚于查询到达。
external_idHMAC SHA-256防重放时间戳受控重试状态查询
核心原则
1. gere external_id no seu banco 2. persista o pedido como "creating" 3. chame a Lunium com o mesmo external_id 4. em timeout, repita exatamente a mesma chamada 5. aceite webhook repetido sem repetir efeito 6. reconcilie por consulta quando houver dúvida
Webhook 处理程序
读取原始请求体
签名依据收到的原始字节计算，重新序列化 JSON 可能产生不同字节序列。
验证时间戳与签名
拒绝无效签名及超出时限的时间戳，使用恒定时间方式比较 HMAC。
按事件标识持久化保存
通过唯一约束保证处理幂等。重复事件应返回成功，不重复产生业务效果。
仅应用有效状态变化
不要因旧事件延迟到达，就回退已经完成的交易。
提交保存后再返回 2xx
持久化失败时返回错误，以便重新投递，不要在保存前确认。
处理伪代码
const raw = await request.rawBody()
verifyLuniumSignature(request.headers, raw)
const event = JSON.parse(raw)
await db.transaction(async tx => {
if (await tx.events.exists(event.event_id)) return
await tx.events.insert(event.event_id, event)
await tx.orders.applyForwardTransition(event.data)
})
return response.status(204)
如何理解失败
创建时超时
使用同一 external_id重试，不新建标识。
重复 webhook
确认事件已持久化保存后，返回 2xx。
延迟 webhook
校验状态变化，不用旧事件覆盖更新的最终状态。
Webhook 遗漏
使用状态查询及投递历史对账。
生产上线前测试
为密钥配置公开 HTTPS URL，并使用 POST /webhooks/test。之后测试重试、错误签名、重复事件及接收端临时不可用。
想在首笔真实 Pix 前审查 webhook 处理器？
仅提供流程结构及测试用 request_id ，不发送密钥、CPF、钱包或含机密资料的 payload。