Um pagamento é aprovado, o provedor envia uma notificação e o sistema libera o pedido. Alguns segundos depois, a notificação chega novamente. Se a integração interpretar cada entrega como uma nova operação, poderá duplicar lançamentos, liberar acesso duas vezes ou enviar mensagens contraditórias. O erro não está necessariamente no provedor: repetição faz parte da realidade de integrações distribuídas.
Idempotência é a propriedade que permite repetir uma solicitação sem repetir indevidamente seu efeito de negócio. Um webhook é uma entrega de informação, não uma garantia de execução única. Este manual trata do consumidor que recebe eventos e do comando que produz efeitos. A arquitetura precisa cuidar dos dois.
1. Separe entrega, evento e operação
Uma entrega é uma tentativa de transporte. Um evento é um fato identificado pelo produtor. Uma operação é o efeito autorizado no seu sistema. Essas entidades devem ter identificadores próprios: a mesma ocorrência pode gerar várias entregas, e diferentes ocorrências podem se referir ao mesmo pedido.
Registre identificador do provedor, identificador do evento, conta de origem, tipo, momento declarado e horário de recebimento. Para o efeito, registre também a chave de negócio: por exemplo, liberação da parcela de uma assinatura. Deduplicar apenas o conteúdo inteiro é frágil, pois campos de transporte podem mudar entre tentativas.
| Camada | Identificador recomendado | Pergunta respondida |
|---|---|---|
| Transporte | ID da tentativa, quando disponível | Quantas entregas ocorreram? |
| Evento | Origem + conta + ID do evento | Esse fato já foi recebido? |
| Negócio | Tipo de operação + objeto + competência | Esse efeito já foi aplicado? |
| Investigação | ID de correlação | Como acompanhar o fluxo completo? |
2. Autentique antes de aceitar
A validação precisa seguir o mecanismo documentado pelo produtor. Na Stripe, por exemplo, a documentação de webhooks descreve verificação de assinatura e tratamento de entregas. A receita específica de um provedor não deve ser copiada para outro sem conferir seus requisitos.
Quando a assinatura depende do corpo bruto, transformar o JSON antes da validação pode invalidá-la. Limite tamanho da requisição, métodos e tipos aceitos. Mantenha credenciais no servidor e permita rotação controlada. Uma origem conhecida não dispensa autorização sobre a conta, o objeto e o ambiente envolvidos: eventos de teste não podem liberar recursos de produção.
3. Persista o recebimento antes de responder sucesso
Um receptor confiável valida o evento, registra uma entrada durável e só então responde conforme o contrato do provedor. Deixar uma tarefa apenas na memória e retornar sucesso cria uma janela de perda se o processo cair. Por outro lado, executar toda a operação dentro da conexão pode provocar timeout e novas entregas.
Uma arquitetura comum usa uma caixa de entrada persistente e um processador assíncrono. O registro pode conter estados como recebido, em processamento, concluído, aguardando nova tentativa e intervenção necessária. A transição de estado deve ser atômica para impedir dois trabalhadores de assumirem o mesmo item simultaneamente.
4. Garanta a exclusividade no armazenamento
Uma consulta prévia do tipo “já existe?” não basta: duas requisições concorrentes podem receber “não” antes de qualquer gravação. Use uma restrição de unicidade adequada no banco, além da lógica de aplicação. O conflito deve produzir um resultado controlado, e não uma segunda execução.
Dentro de uma transação, registre o efeito e a conclusão do processamento quando ambos pertencem ao mesmo banco. Se houver serviços externos, modele explicitamente a possibilidade de resposta perdida. Para publicar eventos a partir de uma mudança local, consulte também o conteúdo sobre transactional outbox.
5. Reutilize a chave ao repetir um comando
Ao chamar um serviço com suporte a chave idempotente, gere a chave para a intenção de negócio e reutilize-a nas tentativas dessa mesma intenção. Uma chave nova a cada retry elimina a proteção pretendida. Uma única chave para operações diferentes também é incorreta.
A referência de requisições idempotentes da Stripe explica o comportamento do serviço, inclusive diferenças entre versões da API. Na sua aplicação, documente duração da chave, resultado de parâmetros divergentes e procedimento para uma operação cujo desfecho ficou desconhecido. Nunca trate um timeout como prova de que nada ocorreu.
6. Controle a ordem e os estados permitidos
Não presuma que as notificações chegarão na mesma ordem em que os fatos aconteceram. Um evento antigo não deve reabrir um pedido encerrado ou substituir uma situação mais recente sem validação. Modele uma máquina de estados com transições permitidas e regras para cancelamento, reversão e atualização tardia.
Quando necessário, consulte o estado atual no produtor por uma API autenticada. Essa consulta tem custo e limites, portanto deve ser reservada às decisões que exigem confirmação. A data do evento é uma evidência, mas não substitui a regra de transição nem resolve sozinha relógios divergentes.
7. Exemplo de homologação
Em um cenário hipotético, uma loja recebe o evento E123 de pagamento aprovado. O receptor valida a assinatura e grava a combinação provedor/conta/E123. Um worker cria a liberação L456 e conclui o registro. A segunda entrega encontra a unicidade já satisfeita e não cria outra liberação.
Agora suponha uma queda depois de chamar um serviço externo, antes de gravar a resposta. O worker deve consultar ou repetir com a mesma chave, conforme o contrato. Se não houver como verificar o resultado, encaminha para análise em vez de gerar uma nova cobrança às cegas. Essa segunda situação é o teste que costuma faltar em protótipos.
8. Checklist de entrada em produção
- Validar assinatura com o formato correto do corpo.
- Recusar conta, ambiente e tipo não autorizados.
- Persistir o evento antes da confirmação de recebimento.
- Impor unicidade no banco e controlar concorrência.
- Testar duplicação simultânea, ordem invertida e timeout.
- Aplicar retentativas limitadas com espera progressiva.
- Separar erros temporários de erros permanentes.
- Permitir inspeção e reprocessamento auditado.
- Monitorar atraso, duplicatas e intervenções pendentes.
Checklist para usar com sua equipe
Baixe o checklist editável em CSV e registre responsáveis, verificações e observações da implantação.
Perguntas frequentes
Responder HTTP 200 impede duplicações?
Não. O retorno confirma uma entrega segundo o contrato de transporte. A prevenção do efeito duplicado pertence à aplicação e ao armazenamento.
Posso apagar imediatamente os eventos concluídos?
A retenção deve considerar a janela de repetição, investigação e necessidades de privacidade. Se apagar o único registro de deduplicação cedo demais, uma nova entrega poderá produzir outro efeito.
Preciso de uma fila para qualquer webhook?
Não necessariamente. O requisito é processamento durável, seguro e dentro do tempo esperado. A fila é uma opção arquitetural, não uma substituta da idempotência.
Como aplicar na empresa
Levante quais eventos alteram dinheiro, estoque, acesso e comunicação. Comece pelo de maior risco e simule as falhas antes de expandir. Para revisar um fluxo existente, converse com a Agência A2CR.
Autoria: Agência A2CR. Revisão editorial: 9 de novembro de 2026. As referências documentam os mecanismos citados; o roteiro de implantação é uma síntese técnica da A2CR, não uma garantia de comportamento de qualquer fornecedor.
