Webhooks, retries, duplicação, assinatura e ordem de eventos

O problema

Muita equipe trata webhook como se fosse só um endpoint comum com iniciativa invertida.

Algo assim:

“O provedor vai fazer um POST aqui e a gente processa.”

Essa explicação e curta demais para ser segura.

Porque webhook real costuma trazer quatro dores junto:

• retry automático
• duplicação
• ordem incerta
• necessidade de validar se aquela mensagem veio mesmo de quem diz que veio

Se você ignora essas quatro coisas, a integração parece simples até o primeiro incidente.

Modelo mental

Webhook e uma notificação externa e assíncrona de um sistema que você não controla.

Isso muda o desenho.

Em vez de pensar “uma request para meu backend”, pense:

“estou recebendo um evento de fora, possivelmente repetido, possivelmente atrasado, e preciso decidir se confio nele e como transformo isso em estado interno seguro.”

Esse modelo mental elimina muita ingenuidade logo no começo.

Quebrando o problema

Retries sao normais

O provedor tenta de novo quando:

• recebeu timeout
• sua aplicação respondeu 5xx
• a confirmação não ficou clara

Isso significa que o mesmo webhook pode chegar mais de uma vez sem que haja bug nenhum no provedor.

Duplicação precisa de deduplicação

Se o provedor manda o mesmo event_id duas vezes, seu sistema não pode:

• criar duas cobrancas
• liberar acesso duas vezes
• mandar o mesmo email dez vezes

O jeito mais comum de tratar isso e guardar um identificador de evento já processado.

Assinatura não e detalhe

Webhook vem de fora.

Logo, você precisa validar se aquela mensagem veio mesmo do provedor esperado e se não foi adulterada.

Assinatura ajuda exatamente nisso.

Ela não substitui:

• autorização interna
• idempotencia
• validação de ordem

Mas sem assinatura, você corre o risco de aceitar evento inventado por qualquer origem.

Ordem de eventos nem sempre e garantida

Esse ponto pega muita gente.

O provedor pode emitir:

1. payment_succeeded
2. refund_created

Mas a entrega pode chegar invertida no seu sistema.

Se a sua lógica depende de “sempre recebo em ordem”, você construiu uma premissa frágil.

Exemplo simples

Imagine um provedor de pagamento mandando webhooks para seu sistema.

Fluxo mais robusto:

1. receber a request
2. validar assinatura
3. extrair event_id
4. registrar que o evento chegou
5. responder rápido
6. processar o efeito de negócio de forma assíncrona e idempotente

Agora, se o mesmo evento vier de novo, o sistema reconhece que já passou por ali.

Se o processamento falhar, você consegue reprocessar sem depender do provedor insistir.

Se a ordem vier estranha, seu modelo interno precisa ser capaz de reconciliar estado sem assumir linearidade perfeita da entrega.

Erros comuns

• Fazer processamento pesado antes de responder o webhook.
• Confiar no corpo recebido sem validar assinatura.
• Assumir que evento chega uma vez só.
• Assumir ordem implicita sem ler a garantia real do provedor.
• Usar retry sem idempotencia e multiplicar efeito colateral.

Como um senior pensa

Quem tem mais experiência trata webhook como integração distribuida, não como formulario vindo de outro sistema.

O raciocínio costuma ser:

“Eu preciso autenticar a origem, aceitar repetição, sobreviver a atraso e desacoplar recebimento de processamento.”

Essa postura parece mais trabalhosa no começo, mas evita integração fraca e incidente chato depois.

O que o entrevistador quer ver

Em entrevista, webhook revela se você entende integração do mundo real.

O avaliador quer ver se você:

• fala de assinatura
• fala de duplicidade
• não assume ordem sem garantia
• sugere resposta rápida e processamento posterior

Uma resposta forte costuma soar assim:

“Eu trataria webhook como evento externo e assíncrono. Validaria assinatura, deduplicaria por event_id, responderia rápido e processaria de forma idempotente sem assumir ordem perfeita.”

Webhook robusto não depende de boa vontade da rede nem da fantasia de ordem perfeita dos eventos.