DEV Community: Rupelio

A engenharia de nunca perder um webhook: fila, retry e idempotência

Rupelio — Thu, 09 Jul 2026 18:50:14 +0000

Por que entregar um webhook de forma confiável é mais difícil do que parece

Todo mundo que já integrou um gateway de pagamento (Kiwify, Hotmart, Stripe, Asaas) conhece o roteiro: a plataforma manda um POST pro seu endpoint avisando "pedido aprovado", e o seu sistema libera o acesso do cliente. Simples. Até o dia em que um cliente paga e não recebe nada, e você descobre que aquele webhook se perdeu no meio do caminho.

O que parece um POST trivial esconde um problema clássico de sistemas distribuídos: entrega confiável entre dois sistemas que falham em momentos diferentes. Este artigo destrincha os pontos que tornam isso difícil e como se resolve cada um. No fim, comento a ferramenta que estou construindo em cima dessas ideias.

O ingênuo: receber e processar

A primeira versão que todo mundo escreve é assim:

POST /webhook -> valida -> libera acesso -> envia e-mail -> responde 200

O problema aparece rápido. Se "libera acesso" e "envia e-mail" demoram, ou dependem de uma API externa lenta, a resposta 200 demora junto. E o remetente (o gateway) não espera pra sempre: ele tem um timeout. Se você não confirma a tempo, ele considera falha, mesmo que seu processamento termine depois. Resultado: do lado dele, "falhou"; do seu lado, pode ter processado, ou não. Ambiguidade.

Ponto 1: responder rápido, processar depois

A primeira correção é desacoplar recepção de processamento:

POST /webhook -> grava o evento cru -> responde 200 imediatamente
(em segundo plano) worker -> lê o evento -> processa

O endpoint agora faz só duas coisas: persistir o payload e responder. Milissegundos. O trabalho pesado sai da frente e roda num worker separado, no seu ritmo. O gateway recebe o 2xx rápido e fica feliz.

Isso introduz a necessidade de uma fila (ou de uma tabela de eventos funcionando como fila). E fila traz os próximos problemas.

Ponto 2: idempotência (o cliente não pode receber o produto duas vezes)

Gateways reenviam webhooks quando acham que falharam. Isso é bom (não perde evento), mas significa que você vai receber o mesmo evento mais de uma vez. Se o seu worker processa cada entrega cegamente, o cliente recebe o produto duas vezes, ou toma dois e-mails, ou você conta a venda em dobro.

A solução é idempotência: cada evento precisa de uma chave estável, e você processa cada chave uma única vez. Um detalhe que pega muita gente: use um identificador do recurso (o id do pedido/venda), não um id da tentativa de entrega. Na Kiwify, por exemplo, o id do "envelope" muda a cada reenvio, então ele não serve pra deduplicar. No banco, um UNIQUE na chave de idempotência resolve de forma limpa: a segunda inserção do mesmo evento simplesmente não entra.

Ponto 3: retry com backoff (o servidor de destino também cai)

Até aqui protegemos contra o nosso endpoint ser lento. Mas o worker, ao entregar o evento pro destino final (o sistema do cliente), enfrenta o mesmo problema ao contrário: e se o destino estiver fora do ar?

Reentregar na hora, em loop, é a pior ideia: você martela um servidor que já está sofrendo. A resposta é backoff exponencial: falhou, espera um pouco e tenta de novo, aumentando o intervalo a cada tentativa (1min, 5min, 15min, 1h). Isso dá tempo do destino se recuperar sem ser bombardeado. E, depois de N tentativas sem sucesso, o evento vai pra uma "fila morta" (Dead Letter Queue) pra inspeção manual, em vez de tentar pra sempre.

Ponto 4: visibilidade e replay

Quando algo dá errado (e vai), você precisa enxergar. Sem log do payload que entrou, do que saiu e da resposta exata do destino, você fica no escuro. Guardar isso permite duas coisas valiosas: diagnosticar ("o servidor devolveu 500 nesse header") e reprocessar em massa (o destino ficou 2h fora, você reenvia todos os eventos daquele período de uma vez, em vez de um por um).

Ponto 5: aguentar o pico

Tudo isso é testado no pior momento: a Black Friday ou o lançamento, quando chegam milhares de eventos em minutos. O endpoint de ingestão precisa ser leve o suficiente pra absorver o pico sem cair (por isso ele só persiste e responde), e a fila precisa segurar o acúmulo enquanto o worker drena no seu ritmo. Desacoplar recepção de processamento não é elegância acadêmica: é o que mantém tudo de pé quando a carga sobe.

Juntando as peças

Uma arquitetura confiável de webhook, no mínimo, tem: um endpoint de ingestão que persiste e responde 2xx na hora; uma fila entre recepção e processamento; idempotência por chave estável; retry com backoff exponencial e uma DLQ; e logs que permitam diagnóstico e replay. Nenhuma dessas peças é exótica sozinha. A dificuldade é que você precisa de todas juntas, corretas, pra não perder um evento, e mantê-las é trabalho contínuo.

Foi partindo disso que comecei a construir o HookSafe: uma camada que fica entre o gateway e o seu servidor, responde 2xx na hora, e cuida de fila, retry, idempotência e replay pra você, sem precisar reescrever o seu sistema. Está em early access. Se o tema te interessa, o problema é mais fundo do que parece, e é um puta exercício de engenharia.

Como você resolve entrega confiável de webhook nos seus projetos? Curioso pra saber as abordagens de vocês nos comentários.

Três bugs que cometi construindo um sistema de confiabilidade (e os três fingiram que deu tudo certo)

Rupelio — Thu, 09 Jul 2026 18:44:35 +0000

Passei os últimos dias construindo o HookSafe, uma camada que fica entre a plataforma de pagamento e o servidor do cliente para garantir que nenhum webhook se perca. A promessa do produto é uma só: se o seu servidor cair, eu seguro o evento e insisto até entregar.

Cometi três bugs no caminho. O que me fez escrever este texto não foi a burrice de cada um, foi perceber, depois, que os três tinham a mesma forma: todos faziam uma falha parecer um sucesso. Num sistema cujo produto é confiabilidade, é difícil imaginar categoria de bug mais cruel.

Bug 1: engoli o erro, e o sistema jurou que tinha entregue

A função que entrega o evento no servidor do cliente ficou assim:

go resposta, err := clienteHTTP.Do(requisicao) if err != nil { return "", nil // <- olhe com carinho }

Eu quis escrever return "", err. Escrevi nil.

O efeito: apontei o destino para uma porta onde não havia nada escutando. O Do devolveu um belo connection refused. E a minha função respondeu ao worker: "sem erro, chefe". O worker, obediente, marcou o evento como entregue, com o status da resposta vazio, e seguiu a vida.

Um evento que nunca saiu do lugar, registrado como entregue. Se isso estivesse em produção, um cliente teria pagado, não receberia nada, e o meu painel mostraria, orgulhoso, que a entrega foi um sucesso.

Aquele if err != nil { return err } que a gente reclama de repetir em Go existe exatamente por isso. A linguagem te obriga a decidir o que fazer com a falha, toda vez. O preço da verbosidade é que ninguém engole um erro sem querer... a menos que digite nil.

Bug 2: o log mentiu

Corrigi o primeiro bug, rodei de novo, e o worker começou a cuspir isto, a cada cinco segundos, para sempre:

worker: erro ao marcar morto 7: ERROR: column "reposta" does not exist worker: evento 7 esgotou as tentativas, marcado como MORTO
Leia as duas linhas de novo. A primeira diz que falhou ao gravar. A segunda anuncia que gravou.

O código:

go if erroBanco := repo.MarkDead(ctx, evento.ID, descricao); erroBanco != nil { log.Printf("erro ao marcar morto %d: %v", evento.ID, erroBanco) } log.Printf("evento %d esgotou as tentativas, marcado como MORTO", evento.ID)
Faltou um continue. O log de sucesso rodava sempre, tivesse a operação funcionado ou não.

O bug original era bobo: escrevi reposta em vez de resposta num UPDATE. Mas o reposta só me custou um minuto depois que eu vi a mensagem de erro. O que quase me custou uma hora foi o log seguinte, afirmando com todas as letras que o evento tinha sido marcado como morto. Eu fui olhar o banco procurando entender por que um evento "morto" continuava sendo processado, quando a resposta estava na linha de cima da minha própria tela.

Um log que mente é pior que a ausência de log. Sem log você sabe que não sabe. Com um log mentiroso, você depura com confiança na direção errada.

E o efeito colateral era divertido: como o MarkDead falhava, o evento nunca saía do status falhou, o next_retry_at já tinha vencido, e o worker o pegava de novo, e de novo, e de novo. Um loop infinito construído a partir de um "s" faltando.

Bug 3: cinco nanossegundos

O worker deveria acordar a cada cinco segundos. Configurei assim:

go WorkerInterval: lerDuracao("WORKER_INTERVAL", 5),
E o log saiu assim:

23:00:09 worker: procurando eventos pendentes... 23:00:09 worker: procurando eventos pendentes... 23:00:09 worker: procurando eventos pendentes... [mais algumas centenas de milhares de linhas no mesmo segundo]
time.Duration, em Go, é um int64 que conta nanossegundos. O literal 5, num lugar que espera uma time.Duration, vira time.Duration(5), que é cinco nanossegundos. O certo é 5 * time.Second, porque time.Second é a constante que vale um bilhão.

Esse é o mais inofensivo dos três, e o único que se anuncia na cara. Mas ele tem um parente perigoso: se você lê a variável de ambiente com time.ParseDuration, o valor precisa vir com unidade ("5s"). Se alguém setar WORKER_INTERVAL=5, o parse falha, o código cai no valor padrão em silêncio, e você fica sem entender por que a configuração não pega.

Ou seja, mesmo o bug bobinho tem uma versão dele que se disfarça de sucesso.

O padrão

Escrevi os três esperando que o texto virasse uma lista de descuidos. Virou outra coisa.

O erro engolido transformou uma falha de rede em uma entrega bem-sucedida. O log mentiroso transformou um UPDATE que não aconteceu em uma confirmação. O parse silencioso transforma uma configuração inválida em um valor padrão. Nenhum dos três derruba o sistema. Todos os três fazem o sistema afirmar com confiança algo que não é verdade.

Software que quebra é chato. Software que mente é caro. E existe uma classe inteira de bugs, os mais difíceis de achar, cuja assinatura é exatamente essa: o caminho de falha existe, mas ele foi escrito para parecer o caminho de sucesso.

O antídoto não é elegante. É desconfiar de todo lugar onde você decide, você mesmo, o que significa "deu certo": todo err que você não propaga, todo log de sucesso que não está guardado atrás de uma verificação, todo valor padrão que substitui uma entrada inválida sem avisar.

Se o seu sistema promete confiabilidade, ele precisa começar sendo honesto consigo mesmo.

O código é aberto: github.com/Rupelio/hooksafe. É um projeto de estudo, e as decisões de arquitetura estão registradas em ADRs no repositório, incluindo a chave de idempotência, que errei duas vezes antes de acertar. Mas essa é outra história.