- 200 OK tende a significar “processado” (ou pelo menos “aceito com garantia”), então evite 200 antes de persistir/enfileirar.
- 202 Accepted é útil quando o processamento é demorado ou depende de terceiros instáveis; reduz timeout e retries do provedor.
- Respostas lentas aumentam duplicidade: muitos provedores reenviam o webhook se não receberem resposta em poucos segundos (o número exato varia).
- Para não perder eventos: valide assinatura, persista o payload, use idempotência e trate retries como comportamento normal.
Defina o que “sucesso” significa para o provedor que envia o webhook
Leia a expectativa do emissor: alguns consideram 2xx como “entregue” e não reenviam; outros reenviam em casos específicos. Sem esse alinhamento, você pode responder 200 e ainda assim ter reentrega — ou pior, perder evento por responder tarde.
Responda rápido (primeiro), processe com segurança (depois)
O padrão mais estável é: (1) validar o mínimo necessário (assinatura/timestamp), (2) persistir/enfileirar o evento de forma durável, (3) responder 200/202, e só então (4) rodar o processamento pesado (CRM, planilhas, IA, etc.).
Escolha 200 ou 202 com base no seu ponto de garantia
Se você só consegue garantir que o evento foi armazenado/enfileirado com segurança, 200 pode ser correto (você “concluiu” a entrega). Se você quer deixar explícito que o trabalho real ainda vai acontecer e pode falhar depois, 202 comunica melhor.
Implemente idempotência para neutralizar duplicidade
Assuma que o mesmo webhook pode chegar mais de uma vez. Use um ID do evento (ou hash do corpo + timestamp/nonce) para rejeitar repetidos, ou para tornar as operações “idempotentes” (repetir não muda o resultado).
Separe erros de validação (4xx) de falhas temporárias (5xx)
Se a assinatura não bate, o payload é inválido ou falta campo obrigatório: responda 400/401/403 (não vale retry). Se seu sistema está indisponível ou a fila caiu: 500/503 (vale retry). Misturar isso gera reenvios inúteis ou perda silenciosa.
O que muda na prática entre 200 OK e 202 Accepted
Em webhooks, o status HTTP não é “só um detalhe”: ele controla retry, timeout e até bloqueio temporário do seu endpoint pelo provedor.
200 OK costuma ser interpretado como “ok, já foi” — então ele só é seguro quando você já fez o essencial para não perder o evento (ex.: validou e persistiu/enfileirou).
202 Accepted é um recado honesto: “recebi, mas vou processar depois”. Ele é especialmente útil quando o processamento pode demorar mais do que o timeout do provedor, ou quando você depende de APIs que variam muito (CRM, e-mail, WhatsApp, gateways).
| Situação | Melhor resposta | Por quê | Risco se escolher errado |
|---|---|---|---|
| Você valida assinatura e grava o evento em banco/fila em milissegundos | 200 | Você já garantiu durabilidade; o restante pode ser assíncrono | Responder 202 sem necessidade pode confundir monitoramento e SLAs |
| Seu fluxo chama 3 APIs externas e pode levar vários segundos | 202 | Evita timeout e retries por lentidão; processa em background | Responder 200 só no final pode gerar duplicidade (retries) e cascata |
| Payload inválido ou assinatura incorreta | 4xx (400/401/403) | Retry não resolve dado ruim ou não autenticado | Responder 200/202 aceita lixo e cria retrabalho/risco de segurança |
| Seu serviço está fora ou sem acesso à fila/banco | 5xx (500/503) | Sinaliza falha temporária para o provedor tentar novamente | Responder 200 “para não reenviar” pode causar perda definitiva |
O padrão que mais evita dor: “ack rápido + processamento assíncrono”
Na prática brasileira (internet variando, provedores com timeout agressivo, e automações que encostam em APIs instáveis), o desenho mais resiliente é: receber → validar → persistir/enfileirar → responder 2xx → processar.
Se você usa n8n/Make/Zapier como receptor, pense no ponto frágil: muitas vezes o workflow inteiro roda dentro do tempo da resposta do webhook. Quando o fluxo cresce, isso vira fábrica de reenvio e duplicidade.
- Validação mínima na borda: assinatura HMAC, timestamp/nonce, tamanho do corpo.
- Persistência: salvar o payload bruto e metadados (headers, receivedAt, IP) para auditoria/reprocesso.
- Idempotência: checar um eventId antes de criar pedido, lead, cobrança, mensagem.
- Fila/DLQ: separar falha temporária de falha “venenosa” (payload sempre quebra).
- Observabilidade: log com correlation-id para rastrear do webhook até o destino final.
Armadilhas comuns (que parecem inocentes)
Responder 200 “só para o provedor parar de reenviar”, antes de gravar o evento: se o processo cair logo depois, você perde o dado e nem sabe.
Fazer chamadas externas dentro do tempo de resposta do webhook: quando a API externa oscila, o provedor reenviará e você criará duplicados (ex.: dois pedidos, duas cobranças, dois tickets).
Tratar todo erro como 500: isso força retries até para payload inválido, lota logs e atrapalha o que é realmente urgente.
Perguntas frequentes
Se eu responder 202, o provedor vai “entender” e não reenviar?
Posso responder 200 e ainda assim processar em background?
Qual é o tempo limite (timeout) típico de um webhook?
Como evitar duplicidade quando o provedor reenviar o mesmo webhook?
Leia também
Webhook no n8n: como receber, tratar e responder HTTP (sem gambiarra)
Aprenda a criar um webhook no n8n, validar assinatura, tratar payload, evitar duplicidade e responder HTTP 200/400/500 com padrão de produção.
Ler →
Webhook ou polling em automações: como escolher (sem perder eventos e sem estourar limites)
Guia direto para decidir entre webhook e polling: latência, confiabilidade, custo por execução, rate limit e como evitar duplicidades. Inclui tabela e checklist prático.
Ler →
Como fazer idempotência em automações com webhook (e parar de duplicar pedidos, notas e leads)
Guia direto para aplicar idempotência em automações com webhook: chaves idempotentes, deduplicação, banco/planilha, retries e boas práticas para n8n/Make/Zapier.
Ler →
Como validar assinatura HMAC em webhook no n8n (e evitar requisição falsificada)
Guia prático para validar assinatura HMAC (SHA-256) em webhooks no n8n, rejeitar requests falsificadas e proteger automações com secret e timestamp.
Ler →