Recentemente, passei por um daqueles momentos em que o mesmo conceito começa a aparecer em contextos completamente diferentes e, quando isso acontece, geralmente é um sinal de que vale a pena prestar atenção.
A bola da vez foi: idempotência.
- Na aula de compiladores da faculdade: idempotência
- Vídeo novo do Augusto Galego sobre: idempotência
- Problema específico no trabalho, o que faltava? Idempotência
Mas enfim, o que significa isso?
Idempotência é uma propriedade da matemática e da computação que descreve operações que podem ser executadas uma ou várias vezes, mas produzem o mesmo estado final como se tivessem sido executadas apenas uma vez.
Trazendo isso para o mundo backend, o problema fica mais interessante quando pensamos em operações reais, com efeitos colaterais reais: criar registros, disparar jobs, consumir APIs externas, processar pagamentos ou alterar estados importantes no sistema.
Nesse artigo, vou contar um pouco sobre como estudei esse conceito de forma aplicada, em um cenário real de problema arquitetural.
O caso📋
Para esse estudo, vou apresentar a evolução de um webhook responsável por processar pagamentos. Nesse cenário, consideramos que o processamento assíncrono executa operações custosas, como chamadas para APIs externas.
Por isso, quando a mesma requisição é processada mais de uma vez, seja por instabilidade de rede, retry automático ou falha temporária na comunicação podemos gerar efeitos indesejados, como custo duplicado, inconsistência de dados ou até o processamento repetido de uma operação que deveria acontecer apenas uma vez.
Como eu fiz 👷♂️
Comecei implementando o webhook puro, sem nenhuma preocupação com processamento duplicado.
Com a rota funcionando, parti para a implementação de diferentes estratégias para lidar com idempotência na operação. Para isso, criei um middleware responsável por interceptar a requisição antes do processamento principal.
Com o tempo, percebi que esse middleware estava ficando cheio de responsabilidades. Além disso, a própria solução foi atingindo diferentes níveis de maturidade conforme eu entendia melhor o problema.
Foi então que decidi separar a implementação em 4 rotas diferentes, a fim de destacar cada nível:
- Sem proteção
- Lock temporário com Redis
- Idempotência persistente no banco
- Idempotência persistente + lock temporário
Fase 1️⃣
Sem mecanismos para idempotência
O problema mora aqui.
Durante o estudo todo vamos considerar a mesma estrutura de payload:
{
"payer_name": "Fulano Rico",
"payer_document": "123456",
"amount_in_cents": 10000,
"bank_code": "001",
"branch_number": "1234",
"account_number": "56789-0"
}
Esse payload representa que o Fulano Rico quer transferir R$ 100,00 para a conta "56789-0".
O problema começa quando lembramos que sistemas distribuídos falham: a rede pode oscilar, a resposta pode demorar, o serviço de origem pode entender que a requisição falhou e, por segurança, reenviar o mesmo evento.
Nesse caso, sem nenhuma implementação para proteção a mesma ação seria processada duas vezes, gerando inconsistências e custos duplicados 🤯
Fase 2️⃣
Redis com hash de payload normalizado
Meu primeiro pensamento foi: “Se o mesmo payload chegar mais de uma vez, vou barrar as próximas requisições e processar apenas a primeira”.
Para começar, precisamos gerar uma chave que identifique a intenção daquele pagamento. Para isso, utilizei a função nativa do PHP hash() para gerar um identificador a partir do payload recebido.
Um detalhe importante aqui é a normalização do payload.
Por exemplo: se o campo payer_name chegar primeiro na primeira requisição e por último na segunda, isso não deveria gerar uma chave diferente. Afinal, apesar da ordem dos campos ter mudado, a intenção da operação continua sendo a mesma.
Por isso, antes de gerar o hash, o payload precisa passar por um processo de normalização, garantindo que a mesma estrutura lógica produza sempre a mesma chave.
Para o payload mencionado na Fase 1, a chave gerada ficaria assim:
"webhook:idempotency:cc4efc0d38d457683b2ece7072e31e55504a04853c48c5799e46921278fff18f"
Com a chave em mãos, o Redis entra como um bloqueio rápido e temporário.
Antes de processar o pagamento, a aplicação tenta salvar essa chave usando SET NX com TTL. O NX garante que a chave só será criada se ela ainda não existir. Na prática, isso significa que a primeira requisição segue o fluxo normalmente, enquanto as próximas, dentro da janela do TTL, são barradas como duplicadas.
Já o TTL evita que essa chave fique registrada para sempre no Redis.
$idempotencyKey = $this->idempotencyKeyGenerator->generate($normalizedPayload);
if (! Redis::set($idempotencyKey, 1, 'EX', 30, 'NX')) {
return response()->json(['message' => 'Request already processed'], 409);
}
//Posteriormente é realizado um Redis::del($idempotencyKey) caso o processamento em si falhe.
Essa solução é muito eficiente em termos de performance e concorrência imediata, mas levanta alguns pontos de atenção:
- O que diferencia um retry do mesmo pagamento de um novo pagamento intencional com os mesmos dados?
- Qual deve ser o tempo ideal de duração desse lock?
- O que acontece se o processamento demorar mais que o TTL?
- O que acontece se a aplicação cair depois de criar a chave, mas antes de concluir o pagamento?
Pensando mais profundamente nessa solução, percebemos uma limitação importante: não temos garantia real sobre a intenção do evento.
Ou seja, dois payloads iguais podem significar a mesma tentativa de pagamento sendo reenviada ou duas tentativas legítimas de pagamento com os mesmos dados.
Fase 3️⃣
Pensando nesse problema, passei a estudar como aplicações reais fazem para diferenciar a intenção da operação.
Uma abordagem comum é utilizar uma Idempotency-Key, enviada pelo consumidor da API, para controlar a unicidade da operação. Esse consumidor pode ser uma máquina de cartão, um gateway de pagamento ou até uma aplicação terceira.
Mas só isso não pareceu suficiente, ainda temos a questão do tempo de bloqueio e a visibilidade de recebimento dos eventos.
Para isso, decidi criar um objeto PaymentWebhookReceipt:
{
"idempotency_key": "webhook:idempotency:{Hash da Idempotency-Key}",
"payload": {
"payer_name": "Fulano Rico",
"payer_document": "123456",
"amount_in_cents": 10000,
"bank_code": "001",
"branch_number": "1234",
"account_number": "56789-0"
},
"status": "received",
"processed_at": null,
"failed_at": null,
"failure_reason": null
}
Esse objeto funciona como um recibo do evento recebido. Ele registra informações importantes, como a chave de idempotência utilizada pelo cliente, o payload original, o status do processamento e os dados relacionados ao resultado da solicitação.
A chave de idempotência deve ser única no banco de dados. Dessa forma, se a mesma chave for recebida novamente, a aplicação consegue identificar que aquela operação já passou pelo sistema antes.
Com a possibilidade dos seguintes status:
case RECEIVED = 'received';
case PROCESSING = 'processing';
case PROCESSED = 'processed';
case FAILED = 'failed';
Ok, mas como ficou esse fluxo na prática?
Um ponto importante é decidir o que acontece quando a operação falha.
A mesma Idempotency-Key pode permitir uma nova tentativa ou exigir uma nova chave, dependendo da regra de negócio.
Agora a identidade da operação está explícita com Idempotency-Key sendo informado pelo cliente, e com o banco de dados como fonte de verdade para saber o status do evento recebido.
Agora temos uma garantia muito mais forte de evitar reprocessamento duplicado da mesma operação.
Porém, toda requisição duplicada tem que chegar no banco dados para conferir a existência. Se pensarmos em um cenário com muitas requisições e muita concorrência isso pode gerar pressão desnecessária no banco de dados.
Fase 4️⃣
Com a solução anterior, temos garantia forte de idempotência, porém podemos melhorar a questão da performance.
Uma solução híbrida, utilizando o Redis para lock rápido e temporário o banco para a rastreabilidade, persistência e fonte de verdade.
Para isso, mantive toda a estrutura de estados da Fase 3, usando o PaymentWebhookReceipt para registrar o ciclo de vida do evento. Também reaproveitei a ideia de lock temporário da Fase 2, mas com uma diferença importante: em vez de gerar a chave a partir do payload, passamos a utilizar a Idempotency-Key enviada pelo cliente.
Além disso, o processo de lock e release também foi melhorado.
Agora, em cada processamento iremos utilizar a seguinte estrutura de chave->valor:
"Idempotency-Key" -> "UUID Gerado na execução para identificar processamento atual"
Dessa forma, o Redis passa a guardar duas informações importantes: a existência do lock e o identificador da execução que está em posse dele naquele momento.
Essa mudança impacta diretamente a forma como fazemos o release do lock. Não basta simplesmente deletar a chave ao final do processamento, porque uma execução atrasada poderia acabar removendo um lock criado por outra requisição.
Por isso, antes de remover a chave, comparamos o UUID da execução atual com o valor salvo no Redis. Essa comparação seguida da remoção precisa acontecer de forma atômica, e é exatamente aqui que entra o script Lua.
if redis.call('get', KEYS[1]) == ARGV[1] then
return redis.call('del', KEYS[1])
end
return 0
Esse script só remove a chave se o valor salvo no Redis ainda for o UUID da execução atual. Caso contrário, ele retorna 0 e preserva o lock, evitando que uma execução antiga remova o lock de outra.
Assim temos um serviço com as seguintes características:
- Eficiente, com Redis fazendo um lock rápido para concorrência em um certo espaço de tempo.
- Persistente, com banco de dados como fonte de verdade.
- Rastreável, mantendo histórico e status do processamento no
PaymentWebhookReceipt; - Mais segura no release do lock, usando Lua para evitar que uma execução remova o lock de outra.
Resultados!
No fim, conseguimos trabalhar diferentes níveis de maturidade do serviço.
Na fase 1 escancaramos o problema.
Na Fase 2, criamos um lock temporário com Redis para lidar com concorrência imediata. Mas ainda pecava em idempotência real, durabilidade e rastreabilidade.
Na Fase 3, passamos a ter uma garantia mais forte e durável de idempotência, baseada em uma Idempotency-Key enviada pelo cliente. Porém, toda requisição duplicada ainda precisava chegar ao banco de dados, o que poderia gerar pressão em cenários de alta concorrência.
Por fim, na Fase 4, combinamos o melhor das duas abordagens anteriores: Redis para lock rápido e temporário, banco de dados como fonte de verdade e Lua para liberar o lock com segurança.
Com isso, chegamos a uma solução mais madura, rastreável, performática e com garantia forte de idempotência.
Conclusão
Esse foi meu estudo arquitetural sobre idempotência aplicado a um webhook de pagamentos.
A principal lição que tirei desse processo é que cada solução traz impactos positivos e negativos para a aplicação.
No fim, cabe a nós, como desenvolvedores e arquitetos, entender os trade-offs, adaptar a solução ao contexto e combinar estratégias para extrair benefícios e mitigar limitações.
E, como quase tudo em arquitetura de software: depende do escopo, do risco e da criticidade da operação.
Muito obrigado por ler até aqui! ❤️
Também deixei o repositório com a implementação completa, testes automatizados para cada fase, ambiente Docker e pipeline de qualidade:
Estudo de Arquitetura: Idempotência em Webhooks de Pagamento
Estudo de arquitetura backend em Laravel sobre idempotência aplicada a webhooks de pagamento.
O objetivo é demonstrar, de forma prática, como diferentes estratégias lidam com o mesmo problema: uma requisição de webhook pode chegar mais de uma vez e não deve gerar efeitos duplicados.
Escopo
Este projeto simula um endpoint de webhook de pagamento que despacha o processamento assíncrono de uma transferência bancária.
O estudo compara quatro abordagens:
- sem proteção contra duplicidade;
- deduplicação temporária com Redis;
- idempotência durável com banco de dados;
- estratégia híbrida usando Redis e banco.
Problema Estudado
Webhooks podem ser reenviados por timeout, falha de rede, retry automático ou concorrência entre entregas próximas.
Sem uma estratégia de idempotência, a mesma intenção de pagamento pode disparar múltiplos jobs, criar registros duplicados ou repetir operações custosas.
Stack
- PHP 8.3+ (Docker e CI em PHP 8.4)
- Laravel 13
- MySQL 8.4
- Redis 7…