Entrar Começar Grátis
Voltar ao blog
webhookstutorialiniciante

O que é webhook e como funciona? Guia completo para desenvolvedores

HookScope ·

Se você trabalha com integrações entre sistemas, já deve ter ouvido falar em webhooks. Eles são a espinha dorsal da comunicação entre aplicações modernas — do Stripe ao GitHub, do Mercado Pago ao Slack.

Neste guia, vamos explicar o que é um webhook, como ele funciona na prática, quando usar e como testar.

O que é um webhook?

Um webhook é uma notificação HTTP automática enviada de um sistema para outro quando um evento acontece. Em vez de você ficar perguntando “aconteceu algo novo?” repetidamente (polling), o serviço te avisa automaticamente.

Na prática, um webhook é um POST HTTP enviado para uma URL que você configura. Quando o evento ocorre (ex: pagamento confirmado), o serviço envia um JSON para a sua URL com os dados do evento.

Exemplo real

Imagine que você integra com o Stripe para receber pagamentos. Quando um cliente paga:

  1. O Stripe detecta o evento payment_intent.succeeded
  2. O Stripe faz um POST para a URL que você cadastrou
  3. Seu servidor recebe o JSON com os dados do pagamento
  4. Você processa (atualiza o pedido, envia email, etc.)
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_3ABC123",
      "amount": 4900,
      "currency": "brl",
      "status": "succeeded"
    }
  }
}

Webhook vs API Polling: qual a diferença?

CaracterísticaWebhookAPI Polling
Quem iniciaO serviço externo (push)Seu sistema (pull)
LatênciaQuase zero — notificação instantâneaDepende do intervalo de polling
Consumo de recursosBaixo — só quando há eventoAlto — requisições constantes
ComplexidadePrecisa de endpoint públicoMais simples de implementar
EscalabilidadeExcelenteProblemático em alto volume

Resumo: webhooks são mais eficientes, rápidos e escaláveis. Use polling apenas quando o serviço não oferece webhooks.

Como funciona um webhook na prática?

O fluxo de um webhook tem 4 etapas:

1. Cadastro da URL

Você configura no serviço externo (ex: Stripe, GitHub) a URL que receberá as notificações. Essa URL precisa ser pública e acessível via HTTPS.

2. Evento acontece

Um usuário faz um pagamento, um commit é pushado, um pedido é criado — qualquer evento que o serviço monitore.

3. Envio do webhook

O serviço faz um request HTTP (geralmente POST) para a URL cadastrada, com um body JSON contendo os dados do evento.

4. Processamento

Seu servidor recebe o request, valida a assinatura (se houver), processa os dados e retorna um status 200 OK.

Importante: se seu servidor não retornar 200, a maioria dos serviços faz retry automático — geralmente com backoff exponencial.

Quais serviços usam webhooks?

Praticamente todos os serviços modernos de API:

  • Pagamentos: Stripe, PagSeguro, Mercado Pago, PayPal, Asaas
  • Código: GitHub, GitLab, Bitbucket
  • Comunicação: Twilio, SendGrid, Slack
  • E-commerce: Shopify, WooCommerce, Hotmart
  • Automação: Zapier, n8n, Make

Desafios comuns ao trabalhar com webhooks

1. URL pública durante desenvolvimento

Em desenvolvimento local, seu localhost não é acessível pela internet. Soluções tradicionais como ngrok criam tunnels temporários, mas as URLs expiram e precisam ser reconfiguradas.

Com o HookScope, você recebe uma URL permanente que nunca expira. Além do dashboard web, você pode usar o HookScope CLI para receber webhooks direto no localhost:

dotnet tool install -g HookScope.Cli
hookscope login
hookscope listen meu-endpoint --to http://localhost:3000

Sem tunnels, sem URLs que mudam a cada sessão.

2. Debugar o payload

Quando o webhook chega e algo dá errado, você precisa ver exatamente o que foi enviado — headers, body, query strings. Ferramentas como o HookScope mostram tudo em tempo real via WebSocket.

3. Testar novamente (replay)

O serviço enviou o webhook, mas seu código tinha um bug. Agora você precisa que o webhook seja enviado de novo. Com replay, você re-envia qualquer webhook capturado com um clique.

4. Garantir idempotência

Webhooks podem ser enviados mais de uma vez (retries). Seu código precisa ser idempotente — processar o mesmo evento múltiplas vezes sem efeitos colaterais.

// Exemplo de idempotência
async function handleWebhook(event) {
  // Verifica se já processou este evento
  const existing = await db.events.findOne({ eventId: event.id });
  if (existing) return; // Já processado, ignora

  // Processa o evento
  await processPayment(event.data);

  // Marca como processado
  await db.events.insert({ eventId: event.id, processedAt: new Date() });
}

Como testar webhooks?

Existem várias abordagens para testar webhooks durante o desenvolvimento:

1. Ferramenta de captura (recomendado)

Use uma ferramenta como o HookScope para capturar webhooks com uma URL permanente. Você pode:

  • Inspecionar headers, body e metadata em tempo real
  • Fazer replay para re-testar sem precisar re-disparar o evento
  • Configurar forward automático para seu localhost
  • Usar o HookScope CLI para receber webhooks localmente via hookscope listen

2. CLI tools (ngrok, localtunnel)

Ferramentas como ngrok criam um tunnel entre a internet e seu localhost. Funcionam bem, mas:

  • URLs temporárias que expiram
  • Precisa reinstalar e reconfigurar
  • Sem histórico de requests anteriores
  • Sem replay de webhooks

Alternativa: o HookScope CLI também encaminha webhooks para o localhost, mas sem tunnels — a URL pública do endpoint nunca muda e você ainda tem acesso ao histórico e replay via dashboard.

3. Mock manual

Você pode simular webhooks manualmente com curl:

curl -X POST http://localhost:3000/webhook \
  -H "Content-Type: application/json" \
  -d '{"type": "payment.confirmed", "amount": 4900}'

O problema é que mocks manuais não reproduzem exatamente o payload real do serviço.

Boas práticas para webhooks

  1. Sempre valide a assinatura — serviços como Stripe enviam um header de assinatura (Stripe-Signature). Verifique antes de processar.
  2. Retorne 200 rapidamente — processe em background se necessário. O serviço espera uma resposta rápida.
  3. Seja idempotente — prepare-se para receber o mesmo webhook mais de uma vez.
  4. Log tudo — registre cada webhook recebido para debugging futuro.
  5. Use HTTPS — nunca receba webhooks em URLs sem TLS.

Conclusão

Webhooks são fundamentais para integrações modernas. Entender como funcionam e ter as ferramentas certas para testá-los faz toda a diferença na produtividade do desenvolvedor.

Se você está começando a trabalhar com webhooks ou quer uma forma mais eficiente de debugar integrações, crie uma conta gratuita no HookScope e comece a capturar webhooks em segundos.

Pronto para testar seus webhooks?

Crie sua conta gratuita e comece a capturar webhooks em segundos.

Começar Grátis