Webhooks assinados via HMAC para o ciclo de vida do off-ramp.
Quando seu produto precisa do estado assíncrono do ciclo de vida, registre endpoints de webhook e verifique cada entrega. A assinatura vincula o timestamp ao corpo bruto exato, permitindo rejeitar payloads adulterados ou reenviados.
Eventos do ciclo de vida
| Evento | Significado |
|---|---|
| deposit.created | Um depósito de vendedor foi criado na Base |
| deposit.partially_filled | Um depósito foi preenchido em parte |
| deposit.filled | Um depósito foi totalmente preenchido |
| deposit.closed | Um vendedor encerrou ou sacou o saldo restante |
| otc.taken | Um depósito OTC privado foi tomado pelo comprador aprovado |
Verifique cada entrega
- 1Leia o header X-Usdctofiat-Signature no formato t=<unix>,v1=<hex>.
- 2Construa o payload assinado como a string timestamp.rawBody usando o corpo bruto, sem parsing.
- 3Calcule o HMAC-SHA256 sobre esse payload com o segredo do seu endpoint.
- 4Compare em tempo constante com o valor v1 em hex antes de confiar no evento.
- 5Opcionalmente, rejeite entregas cujo timestamp seja mais antigo que a janela que você escolheu.
A proteção contra replay é escolha sua
O receptor de referência no repositório de starters trata timestamps mais antigos que 5 minutos como obsoletos para se proteger contra replays. Essa janela é imposta pelo seu verificador, não pelo remetente, então você pode apertá-la ou afrouxá-la conforme sua tolerância a latência e retentativas.
Como a assinatura cobre timestamp.rawBody, faça o parse do JSON apenas depois que a verificação do HMAC passar. Verificar o objeto já parseado em vez dos bytes brutos é o jeito mais comum de errar sutilmente a verificação de assinatura.
Registre e opere
- Registre endpoints com sua API key do Peerlytics; uma única key autentica as superfícies do offramp e do Peerlytics.
- Endpoints que acumulam falhas de entrega consecutivas repetidas podem ser desativados até você corrigi-los.
- Use o receptor do repositório de starters como referência confiável de verificação HMAC.
- Trate webhooks como dicas de estado; reconcilie com a verdade onchain via deposits() quando importar.
Keep exploring
Common questions
Como os webhooks da USDCtoFiat são assinados?
Cada entrega carrega X-Usdctofiat-Signature: t=<unix>,v1=<hex>, um HMAC-SHA256 sobre a string timestamp.rawBody. Recalcule o HMAC com o segredo do seu endpoint sobre o corpo bruto e compare em tempo constante antes de confiar no evento.
Como evito webhooks reenviados?
Rejeite entregas cujo timestamp assinado seja mais antigo que uma janela escolhida por você. O receptor de referência usa 5 minutos. O remetente não impõe uma janela, então isso é responsabilidade do seu verificador.
Preciso de uma API key para webhooks?
Sim. Criar depósitos é permissionless, mas registrar endpoints de webhook usa uma API key do Peerlytics. A mesma key também autentica a API do Peerlytics.