Retries em webhooks: como usar idempotência, backoff e filas

Retries em Webhooks tornam as integrações mais rápidas porque permitem que um sistema receba eventos assim que algo acontece: uma mensagem chegou, foi processada, entregue ou lida, ou uma operação falhou.

O problema é que uma requisição HTTP, sozinha, não garante que o evento será processado corretamente. A conexão pode cair, o endpoint pode responder tarde, o servidor pode retornar erro, o workflow pode falhar depois de receber a requisição ou o mesmo evento pode ser enviado novamente.

Por isso, uma integração confiável precisa considerar quatro situações:

1. O evento pode não chegar;
2. O evento pode chegar mais de uma vez;
3. O evento pode chegar fora de ordem;
4. O processamento pode falhar depois que o evento foi recebido.

A arquitetura precisa combinar retries, backoff, idempotência, filas, dead-letter queues (DLQ) e monitoramento.

Também é importante separar dois fluxos que costumam ser confundidos em integrações com o Z-API:

• Entrega de webhooks: o Z-API envia eventos para o endpoint da empresa;
• Fila de envio de mensagens: a aplicação envia uma mensagem ao Z-API, que a coloca em uma fila para processamento em direção ao aplicativo de mensagem.

Os dois fluxos podem se relacionar, mas não são a mesma coisa. A retentativa de entrega de um webhook deve ser tratada na camada de recebimento. A fila de envio pertence ao caminho entre a aplicação, o Z-API e o app de mensagens instantâneas.

Neste guia, você vai entender como projetar uma arquitetura que reduza perda de eventos, evite duplicidades e permita recuperar falhas sem transformar cada erro em uma nova mensagem para o cliente.

O que é um webhook?

Webhook é uma chamada HTTP disparada por um sistema quando um evento acontece. Em vez de sua aplicação perguntar a cada minuto se existe uma novidade, o provedor envia uma requisição para uma URL configurada.

O fluxo tradicional por consulta funciona assim:

Sua aplicação → “Há uma nova mensagem?” Sua aplicação → “Há uma nova mensagem?” Sua aplicação → “Há uma nova mensagem?”

No webhook, o fluxo é orientado a eventos:

Evento acontece → Provedor chama sua URL → Sua aplicação processa

O n8n, por exemplo, utiliza um Webhook node para receber dados externos e iniciar um workflow. Em uma arquitetura com Z-API, os webhooks podem informar interações e mudanças relacionadas ao processamento das mensagens.

No fluxo de envio, a aplicação envia a mensagem para a API, o Z-API adiciona a solicitação à fila e retorna um identificador. Depois, eventos posteriores podem informar o andamento do processamento, a entrega e a leitura.

O ponto importante é que receber o webhook e concluir o processamento são etapas diferentes.

Por que webhooks falham?

Uma falha de webhook nem sempre significa que o provedor perdeu o evento. O evento pode ter chegado corretamente, mas o processamento pode ter falhado em seguida.

Timeout

O servidor demora para responder. Isso pode acontecer quando o endpoint chama um CRM, consulta um banco, processa uma IA ou espera outro serviço antes de retornar o status HTTP.

O webhook deve responder rapidamente. O processamento pesado deve continuar em uma fila interna ou em um worker separado.

Erro HTTP

Respostas 500, 502, 503 e 504 normalmente indicam falha no servidor ou em uma dependência. Respostas 400 podem indicar payload inválido. Um 401 ou 403 aponta para problema de autenticação ou autorização.

Nem todo erro deve gerar retry. Repetir uma requisição com JSON inválido não corrige o payload.

Falha de rede

O provedor pode não conseguir alcançar seu domínio. DNS, firewall, certificado TLS, rota, proxy ou indisponibilidade podem impedir a conexão.

Deploy ou manutenção

Uma atualização pode reiniciar o serviço no momento em que o webhook é entregue. Sem uma fila no provedor ou no receptor, o evento pode ser perdido.

Falha parcial do workflow

O endpoint responde 200, mas o workflow falha depois. Para o remetente, o evento foi aceito. Para a empresa, a ação não foi concluída.

Essa é uma das razões para separar recebimento de processamento. O endpoint deve registrar o evento de forma durável antes de responder.

Evento duplicado

O mesmo evento pode chegar novamente após timeout ou retentativa. Se a aplicação criar um ticket, emitir uma cobrança ou enviar uma resposta sem verificar se já processou o evento, haverá duplicidade.

A diferença entre retry de webhook e fila de envio do Z-API

Essa distinção é essencial.

Retentativa de entrega de webhook

Nesse fluxo, o Z-API atua como remetente e sua aplicação atua como receptora.

Z-API → POST para seu endpoint → Sua aplicação responde

Se o endpoint estiver indisponível ou retornar um erro temporário, o remetente pode tentar novamente conforme a política aplicável ao serviço. O receptor deve estar preparado para receber o mesmo evento mais de uma vez.

A política exata de retentativas, intervalo e duração deve ser confirmada na documentação vigente e no contrato do serviço. Sua aplicação não deve depender da suposição de que haverá uma quantidade específica de retries.

Fila de envio de mensagens do Z-API

Nesse fluxo, sua aplicação atua como remetente e o Z-API recebe a solicitação.

Sua aplicação → API → fila da API → Aplicativo de mensagem

A aplicação envia uma mensagem ao Z-API. A API recebe a solicitação, coloca o envio em fila e retorna um identificador. A partir daí, eventos posteriores podem informar o processamento, a entrega e a leitura.

Essa fila trata do processamento das mensagens enviadas pela empresa. Ela não substitui a fila que a própria empresa pode precisar para receber e processar webhooks.

Aspecto	Retry de webhook	Fila de envio do Z-API
Direção	Z-API → sua aplicação	sua aplicação → Z-API → Aplicativo de mensagem
Objetivo	Entregar um evento ao seu endpoint	Processar uma mensagem enviada
Controle principal	Remetente e receptor do webhook	Z-API e sua instância de envio
Risco comum	Evento perdido ou duplicado	Mensagem duplicada ou status mal interpretado
Identificador	ID do evento ou da mensagem	ID retornado pela API
Tratamento	Idempotência no consumidor	Controle de envio e acompanhamento de status

Uma arquitetura madura usa as duas camadas: fila própria para consumir eventos e acompanhamento dos IDs de mensagens enviadas.

Retry e backoff: como retentar sem sobrecarregar o sistema

Retry é uma nova tentativa de executar uma operação que falhou. Ele é útil para erros temporários, mas pode piorar uma indisponibilidade quando muitas instâncias repetem a mesma requisição ao mesmo tempo.

Uma estratégia de retry deve combinar:

• limite de tentativas;
• intervalo progressivo;
• jitter aleatório;
• classificação de erros;
• circuit breaker;
• fila para reprocessamento.

Backoff exponencial

No backoff exponencial, o intervalo aumenta a cada tentativa.

Uma fórmula simples é:

intervalo = min(atraso_maximo, atraso_base × 2^tentativa)

Exemplo com atraso base de 1 segundo:

Tentativa	Intervalo aproximado
1	1 segundo
2	2 segundos
3	4 segundos
4	8 segundos
5	16 segundos

Não utilize valores fixos para todos os workers. O objetivo é evitar que um sistema indisponível receba uma nova onda de requisições imediatamente após cada falha.

Jitter

Jitter adiciona uma variação aleatória ao intervalo. Assim, as tentativas se distribuem no tempo.

espera = aleatório(0, min(atraso_maximo, atraso_base × 2^tentativa))

A abordagem com jitter é recomendada em sistemas distribuídos porque reduz sincronização involuntária entre clientes que falharam ao mesmo tempo.

Quando fazer retry?

Em geral, retry faz sentido para falhas temporárias, como:

• timeout;
• conexão encerrada;
• 502 Bad Gateway;
• 503 Service Unavailable;
• 504 Gateway Timeout;
• falha temporária de DNS;
• limite de taxa, respeitando o intervalo indicado.

Evite retry automático para erros que exigem correção:

• 400 Bad Request por payload inválido;
• 401 Unauthorized;
• 403 Forbidden;
• destinatário inválido;
• campo obrigatório ausente;
• evento incompatível com o workflow.

Nesses casos, o evento deve ser encaminhado para análise ou para uma rotina específica de correção.

Limite de tentativas

Nunca dependa de retry infinito. Defina um número máximo de tentativas adequado ao fluxo. Depois desse limite, encaminhe o evento para uma fila de falhas. Ele não deve desaparecer silenciosamente.

Aproveite e conheça plataformas para automatizar fluxos de trabalho com webhooks.

O que é idempotência?

Uma operação é idempotente quando executá-la uma vez ou várias vezes produz o mesmo efeito final.

Imagine que o webhook de “pedido enviado” seja recebido três vezes. O cliente deve receber uma única notificação. Da mesma forma, se um evento de “novo lead” for duplicado, o CRM deve manter uma oportunidade, não criar três.

Idempotência não significa simplesmente ignorar requisições repetidas. Significa identificar que elas representam a mesma operação e reutilizar o resultado já registrado.

Idempotência no recebimento

O evento precisa possuir uma chave estável. Use, nesta ordem, um identificador fornecido pelo provedor ou uma chave composta confiável.

Exemplos:

messageId messageId + eventType instanceId + messageId + eventType orderId + eventType + version

Evite usar o horário de recebimento como chave. O mesmo evento pode chegar em horários diferentes.

Idempotência no envio

Antes de chamar a API para enviar uma mensagem, crie uma chave de operação própria. Por exemplo:

order-9482:shipped:v1

Se o workflow falhar depois de enviar, a retentativa deve consultar se essa chave já possui um messageId. Caso possua, não envie uma segunda mensagem.

Pseudocódigo de deduplicação

A lógica abaixo mostra um consumidor que registra o evento antes de executar o efeito principal.

function processWebhook(event):

eventKey = buildKey(         provider = “z-api”,         instance = event.instanceId,         message = event.messageId,         type = event.eventType     )     existing = idempotencyStore.find(eventKey)     if existing.status == “COMPLETED”:         return HTTP 200     if existing.status == “PROCESSING”:         return HTTP 202     idempotencyStore.insertIfAbsent(         key = eventKey,         status = “PROCESSING”,         receivedAt = now()     )     queue.publish({         key: eventKey,         payload: event     })     return HTTP 202 O worker processa a fila: function consume(message):     record = idempotencyStore.find(message.key)     if record.status == “COMPLETED”:         acknowledge(message)         return     try:         result = executeBusinessAction(message.payload)         idempotencyStore.update(             key = message.key,             status = “COMPLETED”,             result = result,             completedAt = now()         )         acknowledge(message)     catch error:         if isTransient(error) and message.attempts < MAX_ATTEMPTS:             retryWithBackoff(message)         else:             deadLetterQueue.publish(message, error)             idempotencyStore.update(                 key = message.key,                 status = “FAILED”,                 error = error.message             )             acknowledge(message)

O método insertIfAbsent precisa ser atômico. Dois workers não podem inserir a mesma chave simultaneamente.

Como escolher a chave de idempotência?

A chave deve identificar a operação, não apenas o contato. Um contato pode receber várias mensagens diferentes. Usar apenas o telefone ou LID como chave fará a segunda mensagem legítima parecer duplicada.

Uma boa chave combina:

• provedor;
• instância ou canal;
• identificador do evento;
• tipo do evento;
• versão da operação.

Se o evento não tiver um ID confiável, crie uma impressão digital do payload normalizado. Entretanto, tenha cuidado: duas mensagens legítimas com o mesmo conteúdo podem gerar o mesmo hash. 

Inclua campos de contexto, como tipo de evento, origem e ID do objeto.

Filas: por que não processar tudo dentro do webhook?

O endpoint deve fazer o mínimo necessário:

1. validar autenticação;
2. validar estrutura básica;
3. gerar ou extrair a chave de idempotência;
4. persistir o evento;
5. colocar o evento em uma fila;
6. responder rapidamente.

O processamento pesado fica para o worker. Isso inclui:

• consulta ao CRM;
• chamada a um modelo de IA;
• atualização de ERP;
• envio de e-mail;
• criação de ticket;
• cálculo de preço;
• chamada a outros serviços.

Quando o webhook espera a conclusão de todas essas etapas, qualquer lentidão pode ser interpretada como falha de entrega. O remetente pode tentar novamente, criando duplicidade enquanto o primeiro processamento ainda está em andamento.

Fila em memória versus fila durável

Uma lista em memória é rápida, mas pode perder eventos se o processo reiniciar. Para eventos importantes, use armazenamento durável.

Opções comuns incluem:

• Redis com configuração de persistência adequada;
• RabbitMQ;
• Amazon SQS;
• Kafka;
• banco de dados com tabela de eventos;
• fila gerenciada pela própria plataforma de automação.

A escolha depende de volume, ordenação, retenção, custo e capacidade da equipe.

Ordenação

Nem todos os eventos podem ser processados em qualquer ordem. Um status READ antes de RECEIVED pode exigir tratamento diferente de uma atualização de pedido.

Se a ordem importar, use uma chave de ordenação por conversa, contato ou pedido. Evite bloquear toda a fila por causa de uma única conversa.

Dead-letter queue: o que fazer com eventos que falharam?

Uma dead-letter queue, ou DLQ, é uma fila para mensagens que não foram processadas após o número máximo de tentativas.

A DLQ evita dois extremos:

• descartar o evento sem registro;
• repetir indefinidamente uma operação que nunca terá sucesso.

Serviços de fila como o Amazon SQS utilizam uma política de redrive para definir quantas vezes uma mensagem pode ser recebida antes de ser movida para uma DLQ. 

A fila de falhas pode ser inspecionada, analisada e reprocessada depois de uma correção.

O que guardar na DLQ?

Guarde:

• payload original;
• chave de idempotência;
• contador de tentativas;
• último erro;
• stack trace quando apropriado;
• timestamps;
• versão do consumidor;
• nome do workflow;
• origem do webhook;
• motivo da decisão.

Não armazene dados sensíveis sem necessidade. Proteja o acesso à fila e defina política de retenção.

Reprocessamento seguro

Depois de corrigir o problema, o evento pode voltar para a fila principal. O reprocessamento deve manter a mesma chave de idempotência.

Se a ação já tiver sido concluída e apenas o registro estiver inconsistente, o worker deve reconhecer o estado e não repetir o efeito externo.

Precisa saber como diagnosticar instabilidade na API REST de mensageria? Acesse o guia definitivo de 2026 e entenda o que investigar.

Monitoramento de falhas

Uma integração sem observabilidade pode parecer saudável mesmo perdendo eventos. Monitore o caminho completo.

Métricas de entrada

• quantidade de webhooks recebidos;
• taxa de respostas 2xx;
• respostas 4xx e 5xx;
• latência do endpoint;
• timeouts;
• eventos por tipo;
• tamanho da fila de entrada.

Métricas de processamento

• eventos processados;
• tempo de espera na fila;
• tempo de execução do worker;
• taxa de sucesso;
• retries por evento;
• falhas permanentes;
• mensagens na DLQ;
• duplicidades detectadas.

Métricas de envio

• chamadas aceitas pela API;
• IDs de mensagens gerados;
• falhas de envio;
• status de entrega;
• status de leitura;
• tempo entre envio e entrega;
• divergências entre solicitação e confirmação.

O Z-API documenta uma sequência em que a API retorna o ID, a fila é processada e webhooks informam eventos posteriores de processamento, recebimento e leitura. Use esse ID para correlacionar o envio inicial com os status.

Alertas úteis

Crie alertas para:

• aumento súbito de 5xx;
• latência acima do limite;
• fila crescendo continuamente;
• aumento de tentativas;
• primeira mensagem na DLQ;
• queda na taxa de entrega;
• muitos eventos sem chave de idempotência;
• duplicidades acima do padrão;
• webhook sem eventos por período esperado.

Um alerta não deve apenas informar que houve erro. Ele deve apontar o serviço, a instância, o tipo de evento e o próximo procedimento.

Segurança dos webhooks

Retries e filas não compensam um endpoint desprotegido.

Autenticação

Use autenticação por cabeçalho, token, assinatura ou mecanismo suportado pelo provedor. O n8n, por exemplo, oferece autenticação básica, por cabeçalho e JWT para seus webhooks.

Validação do payload

Valide tipos, tamanhos, campos obrigatórios e origem. Não execute ações críticas apenas porque o corpo possui um campo event.

HTTPS

Use HTTPS com certificado válido. Não exponha dados de clientes em URLs ou query strings desnecessariamente.

Rate limiting

Limite requisições por origem e proteja o endpoint contra abuso. O limite deve ser compatível com o volume legítimo do provedor.

Logs seguros

Registre IDs e metadados para diagnóstico. Mascarar telefone, conteúdo e tokens reduz exposição em logs.

Como implementar com n8n, Make ou Zapier?

n8n

Use o Webhook node com URL de teste durante o desenvolvimento e URL de produção após publicar o workflow. Configure autenticação, valide o payload, registre a chave de idempotência e responda rapidamente.

Uma arquitetura simples é:

Webhook n8n    ↓ Validação    ↓ Data Store / banco: chave já processada?    ↓ não Fila ou execução assíncrona    ↓ Ação de negócio    ↓ Registro COMPLETED ou DLQ

Make

Use um Custom Webhook como entrada. O cenário pode armazenar a chave em Data Store, banco ou aplicação externa antes de atualizar CRM ou enviar uma resposta.

Considere que webhooks instantâneos podem ser processados em paralelo. Se a ordem for importante, configure o processamento ordenado ou implemente controle de sequência no sistema de destino.

Zapier

Use Catch Hook para receber o evento e filtre duplicidades por um identificador armazenado em uma base. Para processos críticos, avalie se o histórico, a retenção e os limites do plano são adequados.

Em qualquer ferramenta visual, não confunda “workflow executado” com “efeito concluído”. Registre o resultado da ação externa e trate falhas de cada etapa.

Exemplo completo: mensagem recebida e resposta automática

Suponha que um cliente envie “Quero rastrear meu pedido”.

1. O Z-API envia o evento para o webhook.
2. O endpoint valida o token.
3. A aplicação extrai messageId, contato e conteúdo.
4. A chave de idempotência é criada.
5. O evento é gravado como PROCESSING.
6. O endpoint responde 202.
7. O worker consulta o CRM e o sistema logístico.
8. O worker monta a resposta.
9. A aplicação chama a API do Z-API.
10. O Z-API retorna um novo ID de mensagem.
11. A aplicação salva esse ID.
12. Os webhooks de status atualizam o registro.

Se o evento original chegar novamente, a chave existente impede uma segunda consulta ou uma segunda resposta. Se o CRM estiver fora do ar, o worker faz retry com backoff.

Se o problema persistir, o evento vai para a DLQ. O cliente não recebe cinco mensagens iguais, e a equipe consegue investigar o caso.

Checklist de implementação

• Usar HTTPS no endpoint.
• Configurar autenticação do webhook.
• Validar payload e tamanho da requisição.
• Responder rapidamente após persistir o evento.
• Separar recebimento de processamento pesado.
• Criar chave de idempotência estável.
• Implementar operação atômica de deduplicação.
• Registrar status PROCESSING, COMPLETED e FAILED.
• Usar fila durável para eventos importantes.
• Implementar retry apenas para erros temporários.
• Usar backoff exponencial com jitter.
• Definir limite de tentativas.
• Criar DLQ.
• Monitorar fila e DLQ.
• Salvar o ID das mensagens enviadas pelo Z-API.
• Diferenciar aceitação, processamento, entrega e leitura.
• Testar evento duplicado.
• Testar evento fora de ordem.
• Testar timeout e resposta 500.
• Testar reprocessamento após correção.
• Revisar retenção e proteção dos logs.

Retries em webhooks são necessários em integrações reais

Retries são necessários, mas retry sem idempotência pode transformar uma falha temporária em mensagens duplicadas, tickets repetidos e atualizações inconsistentes.

O desenho mais seguro separa o recebimento do webhook do processamento de negócio. O endpoint valida, registra e coloca o evento em uma fila. O worker processa com chave de idempotência. Erros temporários usam backoff e jitter. Erros permanentes vão para uma dead-letter queue. O monitoramento acompanha entrada, fila, execução, envio e status.

Também é fundamental distinguir os dois sentidos da comunicação. A retentativa de entrega de webhook trata do evento que o Z-API envia para o endpoint da empresa. 

A fila de envio do Z-API trata da mensagem que a aplicação envia para a API e que será processada em direção ao app de mensagem.

Uma integração robusta não presume que eventos chegarão uma única vez, na ordem perfeita ou sem falhas. Ela registra, duplica, retenta, monitora e oferece uma forma controlada de recuperar o que não foi processado.

Consulte a documentação de webhooks do Z-API e implemente seu consumidor com idempotência, filas e monitoramento desde o primeiro fluxo.

Perguntas frequentes

O que é retry em webhook?

É uma nova tentativa de entregar ou processar um evento que falhou. A estratégia deve limitar tentativas e diferenciar erros temporários de erros permanentes.

O mesmo webhook pode chegar duas vezes?

Sim. O consumidor deve assumir que eventos podem ser duplicados e usar uma chave de idempotência antes de executar ações com efeitos externos.

Devo responder 200 somente depois de concluir todo o processamento?

Em muitos casos, não. É mais seguro persistir o evento, colocá-lo em uma fila e responder rapidamente. O worker conclui o processamento de forma assíncrona.

Qual é a diferença entre retry e backoff?

Retry é a tentativa novamente. Backoff é o intervalo progressivo entre tentativas. Jitter adiciona uma variação aleatória para evitar que muitos workers repitam ao mesmo tempo.

O que é uma dead-letter queue?

É uma fila que recebe eventos que falharam após o número máximo de tentativas. Ela preserva o caso para análise e reprocessamento controlado.

A fila de envio do Z-API é a mesma coisa que minha fila de webhooks?

Não. A fila do Z-API processa mensagens enviadas pela sua aplicação em direção ao app de mensagens. Sua fila de webhooks processa eventos recebidos do Z-API.

O ID da mensagem é suficiente para deduplicar tudo?

Ele pode ser uma parte importante da chave, mas a idempotência deve considerar o tipo de evento, a instância e a ação de negócio. A chave correta depende do payload e do fluxo.

Como testar uma integração com retries?

Simule timeout, respostas 500, evento duplicado, evento fora de ordem, falha do CRM, payload inválido e reprocessamento de uma mensagem da DLQ.