Webhook retry automatico: como implementar em 5 passos

Webhook que falha e não tenta de novo é dado perdido. Na prática, um webhook retry automatico resolve a maioria dos problemas de entrega sem você precisar intervir. Neste guia, mostro como implementar um sistema de retry com backoff exponencial, fila de mensagens e alertas, em 5 passos. Você vai precisar de um servidor, um banco de dados (ou Redis) e um serviço de fila (como RabbitMQ, SQS ou BullMQ). Se ainda não tem, comece pelo Passo 1.

Passo 1: Configure uma fila de mensagens

A fila é o coração do retry. Em vez de enviar o webhook direto ao destino, publique o evento na fila. Um worker consome a fila e faz a requisição HTTP. Se falhar, o evento volta para a fila com um atraso programado. Isso evita sobrecarregar o servidor de destino com tentativas simultâneas.

Dica: use uma fila com suporte a atraso por mensagem, como SQS Delay Queues ou RabbitMQ com dead-letter exchange. Evite implementar o atraso com sleep no worker, pois isso bloqueia o processamento.

Passo 2: Defina a política de retry com backoff exponencial

Backoff exponencial aumenta o intervalo entre tentativas a cada falha. Um esquema comum é: 1 minuto, 5 minutos, 30 minutos, 2 horas, 6 horas, 24 horas. Após 6 tentativas, mova o evento para uma fila de dead-letter (DLQ).

Erro comum: usar intervalos fixos (ex: 1 minuto sempre). Isso sobrecarrega o destino e não dá tempo de ele se recuperar. O backoff exponencial reduz a pressão e aumenta a chance de sucesso na segunda tentativa.

Passo 3: Trate apenas falhas transitórias no retry

Nem todo erro merece retry. Se o servidor responde 400 (Bad Request), o problema é no payload, não na rede. Reenviar não vai resolver. Nesse caso, registre o erro e descarte o evento ou envie para uma fila de inspeção manual.

Já erros 500, 502, 503 e timeouts são transitórios. Para timeout, defina um limite claro de resposta, como 5 segundos, e considere falha se o destino não responder dentro desse prazo. Uma resposta fora do range 200 (mesmo um redirect) deve ser tratada como falha.

Passo 4: Adicione idempotência e ordenação

Retry significa que o destino pode receber o mesmo evento mais de uma vez. Para evitar efeitos duplicados, inclua um cabeçalho Idempotency-Key (ou campo no payload) com um UUID do evento. O receptor deve armazenar as chaves já processadas e ignorar reenvios.

A ordenação também importa. Se os eventos dependem uns dos outros, use uma fila sequencial por chave de partição, ou o destino pode processar o evento 2 antes do evento 1, causando estado inconsistente.

Passo 5: Monitore com alertas e métricas

De nada adianta retry se você não sabe que ele está falhando. Métricas essenciais: número de tentativas por mensagem, taxa de sucesso na primeira tentativa, e quantidade de eventos na DLQ. Configure alertas para quando a DLQ crescer além de um limite ou quando a taxa de falha passar de um percentual.

Dica: registre o número de tentativas em cada tentativa (ex: retry_count: 3). Isso ajuda a diagnosticar se o destino está instável ou se o payload está quebrado.

Checklist do que você implementou

• Eventos publicados em fila com atraso configurável
• Backoff exponencial com limites definidos
• Tratamento diferenciado para erros transitórios e permanentes
• Idempotência para evitar processamento duplicado
• Métricas e alertas para falhas persistentes

Com isso, seu webhook retry automatico está pronto para operar. Se o destino ficar fora do ar por horas, o sistema tenta sozinho e avisa quando precisa de ação manual.

FAQ

O que é webhook retry automatico?

É um mecanismo que reenvia automaticamente uma requisição webhook que falhou na primeira tentativa. Ele usa uma fila e uma política de backoff para tentar novamente em intervalos crescentes, até o evento ser entregue ou atingir o limite máximo de tentativas.

Qual a diferença entre retry e dead-letter queue?

Retry é a tentativa de reenvio. A dead-letter queue (DLQ) é uma fila separada para mensagens que falharam todas as tentativas. Ela permite inspecionar o que não foi entregue e reprocessar manualmente, sem perder dados.

Como evitar duplicação de webhook no retry?

Use um cabeçalho Idempotency-Key com um UUID único por evento. O receptor armazena as chaves já processadas e ignora reenvios com a mesma chave. Isso garante que o processamento ocorra apenas uma vez, mesmo com múltiplas tentativas.

Qual o melhor intervalo para retry de webhook?

Não existe um único valor, mas o backoff exponencial é o mais usado. Comece com 1 minuto e dobre a cada tentativa (1, 2, 4, 8, 16, 32 minutos). Limite o máximo em 6 tentativas para não sobrecarregar o destino.

Devo fazer retry para erro 400?

Não. Erro 400 indica problema no payload, e reenviar não resolve. Registre o erro, descarte ou envie para uma fila de inspeção. Retry deve ser reservado para erros transitórios como 500, 502, 503 e timeouts.

Como monitorar o retry do webhook?

Acompanhe métricas como taxa de sucesso na primeira tentativa, número de tentativas por mensagem e quantidade de eventos na DLQ. Configure alertas para quando a DLQ crescer ou a taxa de falha ultrapassar um limite, assim você age antes de perder dados.