Toda integração entre sistemas esbarra na mesma pergunta: como saber que algo aconteceu do outro lado? Existem duas respostas clássicas. Na primeira, sua aplicação pergunta repetidamente se há novidade: é o polling. Na segunda, o outro sistema avisa na hora em que o evento ocorre: é o webhook. Este guia explica como cada modelo funciona, compara os dois com long polling, SSE e WebSocket, e mostra como implementar um webhook receiver seguro em Node.js, PHP e Python.
O que é um webhook?
Webhook é um mecanismo em que um sistema envia uma requisição HTTP (geralmente POST com JSON) para a URL da sua aplicação assim que um evento acontece: pagamento aprovado, pedido enviado, commit no repositório. Em vez de você consultar a API repetidamente, é a API que notifica seu sistema, por isso o modelo é chamado de push.
Na prática, você cadastra uma URL pública no serviço (Stripe, GitHub, Mercado Pago) e implementa um endpoint que recebe e processa esses eventos. O webhook é a forma padrão de receber confirmações de pagamento, atualizações de entrega e eventos de CI/CD em tempo quase real.
O que é Polling?
Polling é a técnica em que sua aplicação consulta a API em intervalos regulares pra verificar se há dados novos: a cada 30 segundos, a cada 5 minutos, conforme a necessidade. É o modelo pull — quem puxa a informação é o cliente.
Tipos de Polling disponíveis
- Short polling: requisições em intervalo fixo. Simples de implementar, mas a maioria das chamadas volta vazia.
- Long polling: o servidor segura a conexão aberta até ter dados ou estourar o timeout, e o cliente reconecta em seguida. Reduz requisições vazias ao custo de conexões mais longas.
Quando o Polling faz sentido?
- A API não oferece webhooks — sobra consultar
- Sua aplicação roda atrás de firewall e não pode expor URL pública
- O dado muda em ritmo previsível (cotação diária, relatório por hora)
- Você precisa de garantia de consistência: o polling sempre traz o estado atual, mesmo que uma notificação se perca
Webhook: A abordagem Push para integrações modernas
O fluxo de um webhook tem três participantes: o provedor (sistema onde o evento acontece), o evento (mudança de estado que dispara a notificação) e o receiver (endpoint HTTP da sua aplicação que recebe o POST).
Anatomia de um Webhook
Uma notificação típica carrega o tipo do evento, o payload com os dados e headers de verificação:
POST /webhooks/pagamentos HTTP/1.1
Host: api.seusite.com.br
Content-Type: application/json
X-Signature: sha256=5d61605c3feea9799210ddcb71307d4ba264225f...
{
"event": "payment.approved",
"id": "evt_8a72f0c",
"created_at": "2026-06-12T09:41:00Z",
"data": { "payment_id": "pay_193124", "amount": 14990, "status": "approved" }
}O header de assinatura (nomes variam: X-Hub-Signature-256 no GitHub, Stripe-Signature na Stripe) permite verificar que a notificação veio mesmo do provedor. É o tema da seção de segurança, adiante.
Comparativo técnico: Polling vs Webhook em diferentes cenários
| Critério | Webhook | Short polling | Long polling | SSE | WebSocket |
|---|---|---|---|---|---|
| Latência | segundos | = intervalo | baixa | baixa | mínima |
| Direção | servidor → você | você → servidor | você → servidor | servidor → cliente | bidirecional |
| Requisições vazias | nenhuma | muitas | poucas | n/a | n/a |
| Precisa de URL pública | sim | não | não | não | não |
| Complexidade | média | baixa | média | média | alta |
| Uso típico | integrações server-to-server | scripts e jobs | chat simples, filas | feed no navegador | jogos, colaboração ao vivo |
Cenários ideais para cada abordagem
Webhook vence quando o evento é imprevisível e a latência importa: confirmação de pagamento, status de entrega, alertas. Polling vence quando você não controla a infraestrutura de recepção ou quando consistência vale mais que velocidade. SSE e WebSocket resolvem outro problema (atualizar o navegador do usuário em tempo real) e não competem com webhooks, que são server-to-server.
Webhook vs API: qual a diferença?
A pergunta engana: webhook é um recurso dentro de uma API, não uma alternativa a ela. Numa API REST tradicional, sua aplicação inicia a conversa e pede dados. No webhook, o fluxo se inverte: o provedor inicia a conversa e entrega os dados. Integrações maduras usam os dois: a API pra ações e consultas, o webhook pra reagir a eventos.
Como criar um webhook receiver (exemplos de código)
O receiver é só um endpoint HTTP que aceita POST. O essencial: responder rápido com 2xx e processar o evento depois.
Node.js (Express)
app.post('/webhooks/pagamentos', express.json(), (req, res) => {
const evento = req.body;
res.sendStatus(200); // confirme o recebimento antes de processar
fila.add('processar-evento', evento); // processe de forma assíncrona
});PHP
$payload = file_get_contents('php://input');
$evento = json_decode($payload, true);
http_response_code(200);
fastcgi_finish_request(); // libera a resposta pro provedor
processarEvento($evento); // continua o trabalho depois da respostaPython (Flask)
@app.route('/webhooks/pagamentos', methods=['POST'])
def receber_webhook():
evento = request.get_json()
fila.enqueue(processar_evento, evento) # Redis Queue, Celery etc.
return '', 200Configurando Webhooks robustos e seguros
Qualquer pessoa que descubra a URL do seu receiver pode enviar um POST forjado. Por isso todo webhook em produção precisa de verificação de origem.
Validação de assinatura HMAC
O provedor assina o corpo da requisição com um segredo compartilhado e envia o resultado num header. Seu receiver recalcula e compara:
const crypto = require('crypto');
function assinaturaValida(req, segredo) {
const recebida = req.get('X-Signature') || '';
const esperada = 'sha256=' + crypto
.createHmac('sha256', segredo)
.update(req.rawBody) // corpo bruto, antes do parse
.digest('hex');
return crypto.timingSafeEqual(
Buffer.from(recebida), Buffer.from(esperada)
);
}Dois cuidados: calcule o HMAC sobre o corpo bruto (o JSON re-serializado pode mudar a ordem das chaves) e use comparação de tempo constante (timingSafeEqual) pra evitar timing attacks.
Garantindo idempotência
Provedores reenviam eventos quando não recebem 2xx a tempo (e às vezes mesmo recebendo). Seu receiver vai processar o mesmo evento duas vezes em algum momento. Guarde o ID do evento processado (Redis com TTL resolve) e ignore repetições. O conceito merece atenção própria: veja o guia de idempotência em APIs.
Tratamento de falhas
Se o seu endpoint ficar fora do ar, o provedor tenta de novo em intervalos crescentes. A Stripe insiste por até 3 dias; o GitHub desiste antes. Não conte com retry infinito: tenha um job de reconciliação que consulta a API periodicamente e recupera eventos perdidos.
Resposta rápida ao Webhook
Provedores aplicam timeout curto (5 a 10 segundos). Se o processamento for além disso, responda 200 imediatamente e jogue o trabalho pesado numa fila. Receiver que processa de forma síncrona acumula timeouts e recebe o mesmo evento em dose dupla.
Como testar webhooks em desenvolvimento
O desafio do desenvolvimento local é que o provedor precisa alcançar sua máquina. Duas ferramentas resolvem:
- webhook.site: gera uma URL descartável que exibe cada requisição recebida. Útil pra inspecionar o payload real de um provedor antes de escrever código.
- ngrok (ou Cloudflare Tunnel): cria um túnel público pro seu localhost, permitindo receber webhooks de verdade na máquina de desenvolvimento.
Serviços maiores ajudam: a Stripe tem CLI que encaminha eventos pro localhost (stripe listen), e o GitHub permite reenviar entregas antigas pelo painel de configuração do webhook.
Implementando Polling de Forma Eficiente
Quando o polling for o caminho, três práticas evitam desperdício:
- Use cursores ou
updated_since: peça só o que mudou desde a última consulta, em vez da lista inteira. - Respeite
ETage304 Not Modified: quando a API suporta, a resposta vazia custa quase nada. - Backoff adaptativo: sem novidade, aumente o intervalo gradualmente; com novidade, encurte. O exemplo abaixo dobra o intervalo até um teto de 5 minutos.
let intervalo = 15_000; // 15s
async function poll() {
const novidades = await consultarAPI();
intervalo = novidades.length
? 15_000
: Math.min(intervalo * 2, 300_000);
setTimeout(poll, intervalo);
}
poll();Estratégias híbridas e arquiteturas modernas
Sistemas críticos combinam os dois modelos numa arquitetura orientada a eventos: webhook como canal principal e polling de reconciliação rodando a cada hora pra capturar o que se perdeu. Provedores de pagamento recomendam exatamente isso. A notificação dá velocidade; a consulta garante que nenhum pagamento aprovado fique sem processar. Pra decidir o que usar na sua API, o critério resume bem: webhook pra eventos, polling pra estado.
Perguntas frequentes
Para que serve um webhook?
Pra receber notificações automáticas de eventos em outro sistema sem ficar consultando a API: confirmação de pagamento, mudança de status de pedido, push em repositório, mensagem recebida. O provedor envia um POST pra sua URL no momento em que o evento acontece.
Qual a diferença entre webhook e API?
API é a interface completa de um serviço; webhook é um recurso da API em que o fluxo se inverte. Na chamada de API tradicional, sua aplicação pede dados. No webhook, o serviço envia dados pra você quando algo acontece.
Como criar um webhook?
Implemente um endpoint HTTP POST público na sua aplicação, cadastre essa URL no painel do serviço que vai notificar e valide a assinatura HMAC de cada requisição recebida. Responda 200 rápido e processe o evento em background.
Webhook é pago?
O mecanismo em si é gratuito — é só uma requisição HTTP. O que pode ter custo é o serviço que envia (alguns planos limitam webhooks) e a sua infraestrutura pra receber, que em geral é mínima.
Webhook é seguro?
É, desde que o receiver valide a assinatura HMAC, use HTTPS e trate eventos duplicados com idempotência. Sem validação de assinatura, qualquer um que conheça a URL consegue forjar notificações.
Conclusão
Webhook e polling resolvem problemas diferentes. Use webhook quando precisar reagir a eventos com baixa latência e puder expor uma URL pública. Use polling quando a consistência importar mais que a velocidade, ou quando o provedor não oferecer notificações. E nos fluxos críticos, combine os dois — webhook pra agilidade, polling de reconciliação pra garantia. Com assinatura HMAC, resposta rápida e idempotência no receiver, a integração aguenta produção sem sustos.
