Webhook não é uma estratégia de confirmação

Webhook é transporte. Confirmação é estado.

Essa diferença parece semântica até o primeiro pagamento que aparece como aprovado no provedor e pendente no seu produto.

O caminho feliz esconde o contrato

No fluxo ideal, o provedor envia um evento, sua API responde 200 e o usuário recebe acesso. Só que a rede não promete ordem, unicidade nem entrega imediata.

Um consumidor de webhook precisa assumir que o evento pode:

• chegar mais de uma vez;
• chegar depois de uma consulta já ter encontrado o pagamento;
• ser processado, mas perder a resposta antes do 200 chegar ao provedor;
• aparecer fora de ordem em relação a outro evento;
• conter uma referência que sua aplicação ainda não conhece.

Responder a essas situações não é trabalho do controller. É parte do modelo de estado.

Idempotência vem antes do efeito

Um identificador único do evento precisa ser persistido antes de disparar efeitos externos. Se a mesma entrega voltar, o consumidor reconhece que ela já foi tratada.

Isso evita a classe mais óbvia de erro: adicionar créditos, emitir nota ou enviar um produto duas vezes.

Mas deduplicar o evento não basta. O próprio efeito também precisa aceitar repetição. Se o processo cair entre registrar o evento e concluir a entrega, a próxima execução deve continuar de onde parou sem criar uma segunda concessão.

Estado vence ordem de chegada

Não trate todo evento como uma instrução para sobrescrever uma coluna.

Um evento atrasado não pode fazer um pagamento voltar de paid para processing. A transição precisa considerar o estado atual, o tipo do evento e, quando existir, a versão ou o horário registrado pelo provedor.

O objetivo não é adivinhar a ordem correta. É impedir uma transição impossível.

Webhook e consulta se complementam

Webhook é ótimo para reduzir latência. Consulta é útil para recuperar verdade.

Uma operação robusta combina os dois:

1. o webhook inicia o processamento normal;
2. uma consulta ao provedor resolve casos ambíguos;
3. um job de reconciliação encontra pagamentos que não produziram efeito interno;
4. métricas mostram eventos com falha e filas envelhecendo.

Em sandbox, a Infi também permite testar o caminho sem depender de um evento externo. A confirmação é explícita, e o estado pode ser consultado depois. O fluxo está em testar no sandbox.

O endpoint do webhook é pequeno. A estratégia ao redor dele é que protege a receita.