Sistemas / SYS.004Explicado

Webhook ou polling: como um sistema avisa o outro que algo aconteceu

Perguntar a toda hora ou receber o aviso no momento certo? Entenda polling e webhook, quando usar cada um e como receber eventos com segurança.

Imagine que você espera uma encomenda. Você pode ir até a portaria a cada dez minutos para perguntar se ela chegou, ou pode deixar seu telefone para que o porteiro avise. Em integrações entre sistemas, a primeira estratégia se chama polling. A segunda é o webhook: um aviso que um sistema envia para outro, automaticamente, no momento em que um evento acontece.

Neste explicado, você vai entender como as duas abordagens funcionam, quando cada uma faz sentido e quais cuidados tornam o recebimento de um webhook confiável. Se você monta automações em ferramentas como o n8n, ou integra serviços de pagamento, formulários e lojas, essa escolha aparece mais cedo do que parece.

O que é polling

Polling é consultar uma API de tempos em tempos para saber se algo mudou. Seu sistema pergunta “tem pedido novo?” a cada cinco minutos, por exemplo. Na maioria das vezes, porém, a resposta é “não”.

A vantagem é a simplicidade. Afinal, quem pergunta controla o ritmo, não precisa expor um endereço público e consegue retomar de onde parou se ficar fora do ar. Por outro lado, a desvantagem é o desperdício e o atraso. Muitas chamadas voltam vazias e, se o intervalo for de cinco minutos, uma mudança pode levar até cinco minutos para ser percebida.

O que é webhook

Um webhook inverte a direção. Ou seja, em vez de você perguntar, o outro sistema avisa. Você cadastra um endereço (uma URL) no serviço de origem e escolhe quais eventos quer receber. Assim que um desses eventos acontece, o serviço envia uma requisição HTTP para esse endereço com os dados do que mudou.

A documentação do GitHub resume a diferença em duas frases: webhooks exigem menos esforço e menos recursos do que fazer polling em uma API, e permitem atualizações quase em tempo real, porque são disparados quando o evento acontece.

Linha do tempo comparando polling e webhook ao longo de uma hora: no polling, doze consultas, a maioria sem novidade, e o evento só é percebido na consulta seguinte; no webhook, um único aviso enviado no instante do evento.
No polling, o sistema pergunta sem parar. No webhook, ele só recebe uma mensagem quando há algo para contar.

Webhook ou polling: como escolher

Webhook não é automaticamente melhor. A própria documentação do GitHub lembra que, se você só precisa da informação uma vez ou de forma esporádica, chamar a API quando precisar resolve. A tabela abaixo resume os critérios mais comuns.

SituaçãoMelhor caminhoPor quê
Você precisa reagir em segundos (pagamento aprovado, formulário enviado)WebhookO aviso chega no momento do evento
O serviço de origem não oferece webhooksPollingÉ a única opção disponível
Você consulta poucos dados, de vez em quandoPolling ou chamada sob demandaMontar um receptor não compensa
Seu sistema não pode ter um endereço públicoPollingO webhook exige uma URL acessível pela internet
Muitos eventos ao longo do diaWebhookEvita milhares de consultas vazias

Além disso, é comum combinar os dois. Dessa forma, o webhook cuida do tempo real, enquanto uma consulta periódica, mais espaçada, confere se algum aviso se perdeu.

Como receber um webhook com segurança

Um webhook é um endereço aberto esperando mensagens. Por isso, ele traz responsabilidades. As boas práticas do GitHub ajudam a montar uma lista de verificação que vale para quase qualquer serviço:

  1. Use HTTPS. A mensagem trafega pela internet e pode conter dados sensíveis.
  2. Valide a origem. Configure um segredo compartilhado e confira a assinatura de cada entrega. Não coloque informações sensíveis na própria URL.
  3. Responda rápido. O GitHub espera uma resposta de sucesso (código 2XX) em até 30 segundos; depois disso, considera que a entrega falhou. Outros serviços têm prazos próprios.
  4. Processe depois. Confirme o recebimento primeiro e trate os dados em segundo plano, com uma fila.
  5. Confira o tipo de evento. Leia o cabeçalho ou campo que identifica o evento antes de agir, porque novos tipos podem surgir.
  6. Evite processar duas vezes. Guarde o identificador único de cada entrega (no GitHub, o cabeçalho X-GitHub-Delivery) e ignore repetições.
Fluxo de recebimento seguro de um webhook: a requisição chega por HTTPS, a assinatura é validada, o sistema responde 2XX rapidamente, a mensagem entra em uma fila, o identificador é conferido para descartar duplicados e só então o evento é processado.
A ordem importa: validar e confirmar primeiro, processar depois. Assim, uma tarefa demorada não derruba a entrega.

O último passo merece atenção. Isso porque serviços reenviam avisos quando não recebem confirmação, e você também pode reenviar manualmente depois de uma falha. Logo, se o seu sistema não reconhece repetições, um único pagamento pode gerar dois pedidos. Tratar a mesma mensagem mais de uma vez sem efeito duplicado é o que se chama de processamento idempotente.

Webhooks em automações no n8n

Em ferramentas de automação, o webhook costuma ser o gatilho que inicia um fluxo. No n8n, o nó Webhook oferece dois endereços, segundo a documentação oficial. A URL de teste funciona enquanto você escuta um evento no editor, por até 120 segundos, e mostra os dados recebidos na tela. A URL de produção só funciona depois que o fluxo é salvo e publicado, e os dados dessas chamadas não aparecem no editor.

Por isso, uma confusão frequente é cadastrar a URL de teste no serviço de origem e estranhar quando nada chega depois. Se você já seguiu o guia sobre como integrar uma API no n8n, o webhook é o caminho inverso: em vez de o seu fluxo chamar o serviço, o serviço chama o seu fluxo.

Antes de trocar polling por webhook

Vale lembrar uma ideia que atravessa várias discussões aqui no Sistemativo: automatizar um processo ruim só faz o erro andar mais rápido. Um webhook acelera o aviso, mas não corrige um fluxo mal desenhado. Antes de trocar a estratégia, pergunte: o que acontece se um aviso chegar duas vezes, fora de ordem ou não chegar? Se você tiver uma resposta para cada caso, a integração está pronta para ganhar velocidade.

/ Conexões

Próximas conexões

Autor

Gledson Dias

Ver todos os artigos

Sistemativo / Brief

Gostou dessa ideia?

A cada duas semanas, ideias, ferramentas, referências e movimentos que valem alguns minutos da sua atenção.

Brief (formulário compacto)

Você poderá sair da lista quando quiser. Sem spam.