DEV Community

Cover image for Aprenda a Testar Webhooks: Ferramentas Essenciais e Tutorial Passo a Passo
Lucas
Lucas

Posted on • Originally published at apidog.com

Aprenda a Testar Webhooks: Ferramentas Essenciais e Tutorial Passo a Passo

Para testar um webhook, você precisa expor uma URL acessível ao provedor, disparar um evento real ou de teste e validar se seu manipulador recebe o payload, verifica a assinatura, responde corretamente e executa o efeito esperado. Como o webhook é enviado pelo provedor para o seu app, o fluxo de teste é diferente de uma chamada REST comum: você precisa capturar requisições de entrada, simular eventos e automatizar asserções.

Experimente o Apidog hoje

Por que webhooks exigem um fluxo de teste diferente

Em uma API REST comum, você controla a requisição: escolhe o método, monta o body, envia e lê a resposta.

Com webhooks, o provedor controla o envio. Ele decide quando chamar seu endpoint, quais cabeçalhos enviar e qual payload usar. Isso cria alguns desafios práticos:

  1. Você nem sempre consegue disparar o evento diretamente. Um evento como payment_intent.succeeded depende do Stripe ou de uma ferramenta de teste do provedor.
  2. A entrega é assíncrona. Seu teste precisa capturar uma requisição recebida, não apenas aguardar um retorno síncrono.
  3. O payload é definido pelo provedor. Seu código precisa aceitar exatamente o formato enviado por Stripe, GitHub, Slack ou outro serviço.
  4. A maioria dos provedores assina as requisições. Seu endpoint deve validar a assinatura antes de confiar no body. Veja também o guia sobre verificação de assinatura de webhook.

Se você ainda está avaliando o padrão arquitetural, estes guias ajudam a comparar alternativas: webhooks vs polling e webhook vs WebSocket.

Ferramentas úteis para testar webhooks

Um fluxo de teste completo normalmente usa quatro tipos de ferramenta:

  • serviço de captura para inspecionar payloads reais;
  • túnel local para expor seu localhost;
  • ferramenta do provedor para disparar eventos;
  • ferramenta de teste para validar resposta e efeitos colaterais.

1. Capture o payload real antes de implementar

Antes de escrever ou ajustar o manipulador, capture um webhook real. Isso evita testar contra um JSON inventado que não representa o payload do provedor.

Serviços comuns:

webhook.site

O webhook.site gera uma URL pública temporária. Tudo que for enviado para ela aparece na interface: método, headers, body e query params.

Use para responder:

  • quais headers o provedor envia?
  • qual é o formato real do body?
  • onde vem o ID do evento?
  • qual header contém a assinatura?

Beeceptor

O Beeceptor fornece um endpoint HTTPS para receber webhooks e inspecionar payloads em tempo real. Também permite configurar mock servers, útil quando você quer capturar e simular usando a mesma ferramenta.

Pipedream RequestBin

O Pipedream RequestBin também permite criar URLs públicas para capturar requisições HTTP. Como limites gratuitos mudam com frequência, verifique a documentação atual do serviço antes de usar em um fluxo recorrente.

Depois de capturar um evento real, salve uma amostra do payload. Você vai reutilizá-la em testes manuais, automatizados e em CI.

2. Exponha seu ambiente local com um túnel

Provedores externos não conseguem acessar localhost:3000 diretamente. Para testar seu manipulador local, use um túnel que gere uma URL HTTPS pública e encaminhe o tráfego para sua máquina.

Usando ngrok 

brew install ngrok

ngrok config add-authtoken $YOUR_TOKEN

ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

O comando imprime uma URL HTTPS pública. Configure essa URL no provedor, por exemplo:

https://abc123.ngrok-free.app/webhooks
Enter fullscreen mode Exit fullscreen mode

Se seu servidor local estiver escutando em:

http://localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

o provedor enviará o webhook para o ngrok, e o ngrok encaminhará para sua aplicação local.

Usando cloudflared 

cloudflared tunnel --url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Assim como o ngrok, o cloudflared imprime uma URL pública que encaminha tráfego para sua porta local.

Esse padrão é útil para depurar com breakpoints, logs e ferramentas do seu editor. Para uma explicação mais detalhada, veja como testar APIs localhost com serviços de webhook.

3. Dispare eventos reais ou de teste do provedor

Depois de ter uma URL pública, você precisa fazer o provedor enviar um evento.

Stripe CLI

O Stripe CLI permite encaminhar eventos da sandbox para seu endpoint local.

stripe listen --forward-to localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

Para filtrar eventos específicos:

stripe listen \
  --events payment_intent.succeeded,checkout.session.completed \
  --forward-to localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

O comando também imprime um segredo de assinatura. Configure esse segredo na sua aplicação para validar o header Stripe-Signature.

Com o listener ativo, dispare eventos de teste:

stripe trigger payment_intent.succeeded

stripe trigger checkout.session.completed

stripe trigger --help
Enter fullscreen mode Exit fullscreen mode

Atenção: alguns triggers criam objetos de API relacionados e podem gerar eventos em cascata. Por exemplo, payment_intent.succeeded também pode emitir payment_intent.created.

GitHub

O GitHub permite reentregar webhooks recentes.

Fluxo:

  1. Abra o repositório.
  2. Vá em Settings.
  3. Acesse Webhooks.
  4. Clique na URL do webhook.
  5. Abra Recent Deliveries.
  6. Selecione uma entrega.
  7. Clique em Redeliver.

Restrições importantes:

  • só é possível reentregar eventos dos últimos 3 dias;
  • você precisa ter acesso de administrador ao repositório;
  • o GitHub não reenvia automaticamente entregas com falha.

Slack

Webhooks de entrada do Slack são simples de testar: basta fazer um POST com JSON para a URL do webhook.

curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
  -H 'Content-type: application/json' \
  -d '{"text":"Hello, world."}'
Enter fullscreen mode Exit fullscreen mode

A URL do webhook do Slack é um segredo. Não coloque essa URL no frontend, em repositórios públicos ou em logs expostos.

4. Valide seu manipulador com payloads repetíveis

Capturar e disparar eventos confirma que a conexão funciona. Mas você ainda precisa validar se o manipulador está correto.

Um teste mínimo pode ser feito com curl:

curl -X POST http://localhost:3000/webhooks \
  -H 'Content-Type: application/json' \
  -H 'Stripe-Signature: t=...,v1=...' \
  -d '{
    "id": "evt_test",
    "type": "payment_intent.succeeded",
    "data": {
      "object": {
        "id": "pi_123",
        "status": "succeeded"
      }
    }
  }'
Enter fullscreen mode Exit fullscreen mode

Esse teste é útil para smoke test, mas não escala bem. Para testes repetíveis, salve payloads, headers e asserções em uma ferramenta de API.

Testando webhooks com Apidog

Apidog é uma plataforma para projetar, depurar, testar, simular e documentar APIs.

Ele não funciona como uma “caixa de entrada de webhook” dedicada. O uso mais prático para webhooks é:

  • montar payloads de exemplo;
  • salvar requisições reutilizáveis;
  • validar respostas com asserções;
  • simular provedores com mock server;
  • executar cenários em CI com o Apidog CLI.

Crie uma requisição reutilizável para o webhook

Pegue o payload capturado em uma ferramenta como webhook.site ou copiado da documentação do provedor.

No Apidog:

  1. Crie uma nova requisição.
  2. Defina o método como POST.
  3. Configure a URL do seu endpoint, por exemplo: 
http://localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode
  1. Cole o JSON no body.
  2. Adicione os headers enviados pelo provedor, por exemplo: 
Content-Type: application/json
Stripe-Signature: t=...,v1=...
Enter fullscreen mode Exit fullscreen mode
  1. Salve a requisição.

Agora você tem um teste repetível para enviar um payload conhecido ao seu manipulador sem reescrever comandos curl.

Crie variações para cobrir casos como:

  • payload válido;
  • campo obrigatório ausente;
  • assinatura inválida;
  • evento duplicado;
  • tipo de evento não suportado.

Adicione asserções para validar a resposta

Enviar o payload não basta. Você precisa validar o retorno do endpoint.

No Apidog:

  1. Abra a requisição ou cenário.
  2. Vá em Processadores Pós-execução.
  3. Clique em + Adicionar.
  4. Escolha Asserção.
  5. Configure a regra de validação.

Exemplo de asserção:

JSONPath: $.data.status
Condição: Igual a
Valor esperado: succeeded
Enter fullscreen mode Exit fullscreen mode

Você também pode validar o status HTTP:

Status code == 200
Enter fullscreen mode Exit fullscreen mode

Para cenários de erro:

Status code == 400
Enter fullscreen mode Exit fullscreen mode

ou:

Status code == 401
Enter fullscreen mode Exit fullscreen mode

quando a assinatura for inválida.

Asserções visuais comparam valores como strings. Se precisar validar tipos com precisão, como número ou booleano, use script customizado com sintaxe pm.test compatível com Postman.

Exemplo conceitual:

pm.test("status deve ser succeeded", function () {
  const json = pm.response.json();
  pm.expect(json.data.status).to.eql("succeeded");
});
Enter fullscreen mode Exit fullscreen mode

Use mock server para simular um provedor

Em alguns testes, seu serviço chama uma API externa depois de receber o webhook. Para evitar chamadas reais durante o desenvolvimento, você pode simular essa API com o mock server do Apidog.

O Apidog oferece três tipos de mock:

  • Mock Local: roda com o cliente desktop e só funciona enquanto ele estiver aberto.
  • Mock na Nuvem: hospedado pelo Apidog, funciona continuamente e pode ser ativado ou desativado.
  • Mock Runner: executado em infraestrutura auto-hospedada e compartilhado com a equipe.

Cada endpoint HTTP tem um módulo de mock. Copie a URL do mock na aba API em modo Design ou na aba Mock em modo Debug.

Importante: apenas caminhos que começam com / roteiam para o ambiente de mock.

Use essa URL em testes para obter respostas previsíveis sem chamar o provedor real.

Execute testes de webhook em CI com Apidog CLI

Depois que o cenário passar localmente, execute-o em CI.

Instale o CLI:

npm install -g apidog-cli
Enter fullscreen mode Exit fullscreen mode

Verifique a instalação:

node -v
apidog -v
which node
which npm
which apidog
Enter fullscreen mode Exit fullscreen mode

O Apidog CLI requer Node.js v16 ou superior.

Execute um cenário salvo:

apidog run \
  --access-token $APIDOG_ACCESS_TOKEN \
  -t 637132 \
  -e 358171 \
  -d 3497013 \
  -r html,cli
Enter fullscreen mode Exit fullscreen mode

Parâmetros:

  • -t: ID do cenário de teste;
  • -e: ID do ambiente, obrigatório;
  • -d: dados de teste, como arquivo CSV/JSON ou ID de dataset;
  • -r: reporters, como cli, html, json ou junit.

Para detalhes de uso, veja o tutorial do Apidog CLI.

Quer montar e validar testes de webhook visualmente? Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito.

Fluxo recomendado para testar webhooks

Use esta sequência como checklist:

  1. Capture um payload real.

    Aponte o provedor para uma URL do webhook.site ou ferramenta similar.

  2. Analise headers e assinatura.

    Identifique Content-Type, header de assinatura, ID do evento e formato do body.

  3. Suba seu manipulador local.

    Execute sua aplicação em uma porta local, por exemplo localhost:3000.

  4. Abra um túnel.

    Use ngrok http 3000 ou cloudflared tunnel --url http://localhost:3000.

  5. Configure a URL pública no provedor.

    Exemplo:

   https://abc123.ngrok-free.app/webhooks
Enter fullscreen mode Exit fullscreen mode

  1. Dispare um evento real ou de teste.

    Use stripe trigger, o botão Redeliver do GitHub ou um POST do Slack.

  2. Teste assinatura válida e inválida.

    O manipulador deve aceitar a requisição válida e rejeitar a adulterada.

  3. Valide resposta e efeitos colaterais.

    Verifique status HTTP, body, escrita no banco, publicação em fila ou chamada downstream.

  4. Automatize.

    Salve o cenário no Apidog e execute com Apidog CLI no CI.

Se você está projetando o sistema de webhooks, veja também como projetar webhooks confiáveis e melhores práticas de webhook de pagamento. Para contexto arquitetural, consulte o guia da API de webhooks e webhooks e arquitetura orientada a eventos.

Perguntas frequentes

Como testar um webhook?

Forneça ao provedor uma URL acessível, dispare um evento real ou de teste e valide se seu endpoint recebeu o payload, verificou a assinatura, retornou o status correto e executou o efeito esperado.

Como testar webhooks localmente?

Execute seu manipulador localmente e exponha a porta com um túnel:

ngrok http 3000
Enter fullscreen mode Exit fullscreen mode

ou:

cloudflared tunnel --url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

Depois, configure a URL HTTPS pública no provedor e dispare um evento.

Como testar um webhook com Postman?

Você pode usar o Postman para enviar um POST com payload e headers personalizados para seu endpoint. Ele é útil para validar resposta, mas não recebe webhooks reais sozinho. Para capturar eventos reais, combine com um serviço de captura ou túnel. O mesmo se aplica ao Apidog.

Como testar webhooks do Stripe?

Use o Stripe CLI:

stripe listen --forward-to localhost:3000/webhooks
Enter fullscreen mode Exit fullscreen mode

Depois dispare um evento:

stripe trigger payment_intent.succeeded
Enter fullscreen mode Exit fullscreen mode

Use o segredo exibido pelo stripe listen para validar o header Stripe-Signature.

Como testar um webhook do Slack?

Envie um POST JSON para a URL de webhook de entrada:

curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
  -H 'Content-type: application/json' \
  -d '{"text":"Hello, world."}'
Enter fullscreen mode Exit fullscreen mode

Se o teste funcionar, a mensagem aparecerá no canal configurado.

Como testar uma URL de webhook?

Envie um POST de amostra e confirme o status HTTP, o body da resposta e os efeitos colaterais. Para um teste mais confiável, use um payload real capturado, teste assinaturas válidas e inválidas e automatize asserções.

Top comments (0)