Quais eventos um checkout cripto emite?

A InfraIO Pay dispara um webhook para cada transição de estado. Essa máquina de estados é propositalmente pequena, para que você conecte o fulfillment a exatamente um evento e ignore o resto.

  • payment.pending, o comprador transmitiu a transação; as confirmações ainda estão se acumulando.
  • payment.confirmed, a transação atingiu o limiar de confirmação da sua rede.
  • payment.settled, os fundos foram varridos para sua carteira de liquidação. Faça o fulfillment aqui.
  • session.expired, a janela de checkout fechou sem pagamento. Nunca é cobrado.

Em qual evento você deve fazer o fulfillment?

Faça o fulfillment em payment.settled. Uma transação pending ainda pode falhar em confirmar, e os limiares de confirmação variam por rede, então tratar qualquer estado anterior como definitivo arrisca você despachar um pedido contra um pagamento que nunca se concretiza. A liquidação é o ponto em que o dinheiro é irreversivelmente seu.

Se você precisar mostrar progresso ao comprador, pode exibir pending e confirmed na sua UI, mas mantenha a ação irreversível (despachar, conceder acesso, mintar) vinculada ao settled.

Como você verifica se um webhook é genuíno?

Todo webhook é assinado com o secret do seu endpoint. Recalcule o HMAC sobre o corpo bruto da requisição e compare-o em tempo constante com o cabeçalho de assinatura; rejeite qualquer coisa que não coincida. Se você é novo em HMAC, a referência SubtleCrypto.sign da MDN é uma boa introdução, e o guia de boas práticas de webhooks da Stripe cobre bem o lado operacional.

Verifique antes de fazer parse ou agir. Uma requisição sem assinatura ou com assinatura incorreta nunca deve chegar à sua lógica de negócio.

Como tornar a entrega segura para retry?

Webhooks são entregues pelo menos uma vez (at-least-once), então o mesmo evento pode chegar mais de uma vez depois de uma instabilidade de rede. Cada evento carrega uma chave de idempotência; registre as chaves que você já processou e não faça nada (no-op) em repetições. Responda 2xx rapidamente e execute trabalho lento de forma assíncrona, para que quem envia não sofra timeout e faça retry sem necessidade. A InfraIO mantém um log de entregas com replay de um clique para as vezes em que você precisar reprocessar deliberadamente.