Webhooks duplicados: como aplicar idempotência

Um webhook informa que algo aconteceu em outro sistema. Se a confirmação da entrega se perde, o remetente pode tentar novamente. O problema aparece quando cada recebimento cria um negócio, lança uma cobrança ou envia uma mensagem sem reconhecer que o mesmo evento já foi tratado. Idempotência é a propriedade de repetir uma operação sem repetir indevidamente seu efeito.

Considere uma empresa fictícia de manutenção. O sistema de contratos envia o evento “contrato aprovado” para abrir uma implantação no CRM. O evento chega duas vezes porque a primeira resposta demorou. A expectativa é encontrar uma implantação associada ao contrato, mesmo que o mecanismo de entrega tenha feito mais de uma tentativa.

Identifique o evento e a operação de negócio

Guarde o identificador fornecido pelo remetente junto com a origem e a conta à qual ele pertence. A combinação pode evitar colisões entre ambientes ou clientes diferentes. Não use apenas o horário de recebimento: cada tentativa teria um horário novo e passaria pela verificação como se fosse inédita.

A documentação de webhooks da Stripe descreve entregas duplicadas e recomenda registrar IDs já processados. Ela também mostra que eventos distintos podem corresponder à mesma situação de negócio. Essa distinção ajuda a separar “mesmo envelope entregue novamente” de “novo envelope que tenta produzir o mesmo efeito”. As chaves corretas dependem do contrato do fornecedor.

Registre estados, não apenas uma lista de recebidos

Marcar como concluído antes de executar pode perder uma operação se o serviço cair. Executar e só depois tentar gravar a conclusão pode produzir duplicata na próxima tentativa. Quando efeito e registro pertencem ao mesmo banco, uma transação pode unir essas mudanças. Quando envolvem sistemas diferentes, é necessário desenhar recuperação para o intervalo entre elas.

Proteja o processamento concorrente

Duas entregas podem chegar ao mesmo tempo. Consultar uma tabela, encontrar ausência e inserir depois não resolve sozinho: os dois trabalhadores podem ver a mesma ausência. Use a garantia adequada do armazenamento, como uma restrição de unicidade na chave do evento e uma transição de estado controlada. A implementação deve tratar a disputa como um caso esperado.

Se outro trabalhador já estiver processando, não execute o efeito novamente. Registre a entrega adicional e siga a política de confirmação e recuperação escolhida. Trabalhos que ficaram em processamento por uma interrupção precisam de um mecanismo explícito de retomada. Um estado permanente de “ocupado” pode esconder uma operação abandonada.

Confira o efeito na outra ponta

No exemplo da manutenção, mantenha a relação entre CT-18 e IM-72. Antes de recriar uma implantação após falha de comunicação, consulte essa referência quando a API permitir. Se o destino oferecer chave de idempotência, utilize-a conforme a documentação e respeite o prazo de retenção da chave. Não suponha que todo CRM tenha esse recurso.

Uma atualização do estado atual pode ser naturalmente mais fácil de repetir do que um comando de “incrementar contador”. Enviar uma comunicação externa também exige cuidado: desfazer o registro local não recolhe uma mensagem que o cliente já recebeu. Liste esses efeitos irreversíveis no contrato da integração.

Teste os pontos onde a confirmação pode se perder

• Entregue o mesmo ID duas vezes, em sequência.
• Entregue o mesmo ID simultaneamente por dois trabalhadores.
• Interrompa o processamento antes do efeito e depois dele.
• Simule resposta perdida após o destino concluir a operação.
• Envie evento diferente para o mesmo contrato e confira a regra de negócio.

Em cada teste, conte os efeitos produzidos e examine o estado final do registro. Uma resposta HTTP bem-sucedida, sozinha, não comprova que houve apenas uma implantação. Guarde também o resultado da tentativa anterior, quando necessário, para responder de forma consistente às repetições.

A retenção dos registros de idempotência deve considerar a janela de reentrega do fornecedor e a necessidade de auditoria aprovada pela empresa. Antes de implementar, alinhe esses pontos ao contrato de dados da integração. O resultado esperado é uma operação recuperável mesmo quando a entrega deixa de ser perfeita.