Blog

Como Testar APIs Localhost com Serviços Webhook?

Ashley Innocent

Ashley Innocent

28 janeiro 2026

Como Testar APIs Localhost com Serviços Webhook?

Testar APIs locais (localhost) que precisam receber webhooks ou callbacks de serviços externos exige expor temporariamente seu servidor de desenvolvimento local à internet. Serviços de tunelamento como ngrok, NPort, Cloudflare Tunnel e outros criam conexões seguras que fornecem ao seu localhost uma URL pública.

💡
Baixe o Apidog para acompanhar os fluxos de trabalho de teste de webhook neste guia. Este guia abrange como escolher a ferramenta certa, configurar o tunelamento, testar webhooks de forma eficaz usando o Apidog e lidar com desafios comuns como autenticação, limites de taxa e depuração.
botão

Por Que Você Precisa de Tunelamento Localhost

Você está construindo uma API que se integra com serviços de terceiros. Tudo funciona no seu laptop—endpoints respondem corretamente, os dados fluem sem problemas. Então você tenta testar callbacks de webhook do Stripe, GitHub, Twilio ou qualquer serviço externo.

Problema: Serviços externos não conseguem alcançar localhost:3000. Seu servidor de desenvolvimento não está acessível pela internet.

Cenários comuns onde isso interrompe seu fluxo de trabalho:

1. Teste de Webhook

Serviços como Stripe enviam confirmações de pagamento, GitHub envia eventos de repositório, Slack envia eventos de interação—tudo como requisições POST para sua API. Durante o desenvolvimento, esses serviços precisam de uma URL pública para enviar webhooks.

2. URLs de Callback OAuth

Ao implementar "Fazer login com o Google", "Fazer login com o GitHub" ou qualquer fluxo OAuth, o provedor de autenticação redireciona os usuários de volta para sua aplicação com um código de autorização. A URL de redirecionamento deve ser publicamente acessível e corresponder ao que você registrou com o provedor.

3. Integração de API de Terceiros

Algumas APIs exigem URLs de callback para operações assíncronas. Por exemplo, serviços de transcodificação de vídeo notificam sua API quando o processamento é concluído, ou processadores de pagamento confirmam transações.

4. Desenvolvimento de Aplicativos Móveis

Testar sua API a partir de um dispositivo móvel na mesma rede geralmente falha porque o aplicativo móvel não consegue resolver localhost. Um túnel fornece uma URL que funciona em qualquer dispositivo.

5. Demonstrações para Clientes

Às vezes, você precisa mostrar o trabalho em andamento para clientes ou partes interessadas. Implantar em staging para cada pequena alteração retarda a iteração. Uma URL pública temporária permite que os clientes testem seu ambiente de desenvolvimento.

Como Funciona o Tunelamento Localhost

Serviços de tunelamento criam uma conexão segura entre seus servidores em nuvem e sua máquina local:

Serviço Externo → Serviço de Tunelamento (URL pública) → Conexão Segura → Seu Localhost:3000

O processo:

  1. Você inicia um cliente de túnel em sua máquina apontando para sua porta local
  2. O cliente se conecta à infraestrutura de nuvem do serviço de tunelamento
  3. O serviço atribui uma URL pública (por exemplo, https://abc123.ngrok.io)
  4. Requisições de entrada para essa URL pública são encaminhadas através da conexão criptografada para o seu localhost
  5. Seu servidor local recebe a requisição como se ela viesse diretamente do cliente
  6. As respostas retornam através do túnel para o solicitante

Isso acontece de forma transparente. Seu servidor local não precisa saber que está por trás de um túnel.

Comparando Serviços de Tunelamento Populares

Aqui estão as opções mais populares em 2026, com seus pontos fortes e limitações:

Melhor para: Projetos estabelecidos, equipes que buscam confiabilidade

ngrok http 3000

Prós:

Contras:

Camada Gratuita:

Planos Pagos: US$ 8-20/mês

NPort (Alternativa Gratuita em Ascensão)

Melhor para: Desenvolvedores que evitam custos de assinatura

nport start 3000

Prós:

Contras:

Camada Gratuita:

Esta é a ferramenta que está ganhando força no Dev.to à medida que os desenvolvedores procuram alternativas ao ngrok sem custos contínuos.

Cloudflare Tunnel (Melhor para Próximo à Produção)

Melhor para: Equipes que já usam Cloudflare, túneis de longa duração

cloudflared tunnel --url http://localhost:3000

Prós:

Contras:

Camada Gratuita:

Localtunnel (Mais Simples)

Melhor para: Testes rápidos e únicos, sem instalação

npx localtunnel --port 3000

Prós:

Contras:

Camada Gratuita:

Tailscale Funnel (Melhor para Equipes)

Melhor para: Compartilhamento privado em equipe, demos seguras

tailscale serve https / http://localhost:3000
tailscale funnel 443 on

Prós:

Contras:

Camada Gratuita:

Tabela Comparativa

RecursongrokNPortCloudflare TunnelLocaltunnelTailscale
PreçoGrátis/US$ 10+GrátisGrátisGrátisGrátis/Pago
Limite de Sessão2 horasNenhumNenhumNenhumNenhum
Domínio PersonalizadoPagoGrátisSimNãoSim
Inspetor de RequisiçõesSimBásicoNãoNãoNão
Complexidade da ConfiguraçãoBaixaBaixaMédiaMuito BaixaMédia
ConfiabilidadeExcelenteBoaExcelenteRuimExcelente
Melhor ParaTeste de produçãoDesenvolvedores conscientes do custoEmpresasTestes rápidosCompartilhamento em equipe

Configurando Seu Primeiro Túnel Localhost

Vamos ver a configuração com as ferramentas mais comuns. Usaremos uma API Express Node.js como exemplo, mas isso funciona com qualquer servidor local.

Exemplo: Servidor API Local

// server.js
const express = require('express');
const app = express();

app.use(express.json());

app.post('/webhook', (req, res) => {
  console.log('Webhook received:', req.body);
  res.json({ received: true });
});

app.get('/health', (req, res) => {
  res.json({ status: 'healthy' });
});

app.listen(3000, () => {
  console.log('Server running on http://localhost:3000');
});

Opção 1: Usando ngrok

Passo 1: Instale o ngrok

# macOS
brew install ngrok

# Windows (via Chocolatey)
choco install ngrok

# Linux
curl -s https://ngrok-agent.s3.amazonaws.com/ngrok.asc | \
  sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null && \
  echo "deb https://ngrok-agent.s3.amazonaws.com buster main" | \
  sudo tee /etc/apt/sources.list.d/ngrok.list && \
  sudo apt update && sudo apt install ngrok

Passo 2: Autentique (opcional, mas recomendado)

ngrok config add-authtoken YOUR_AUTH_TOKEN

Passo 3: Inicie o túnel

ngrok http 3000

Saída:

Session Status                online
Account                       you@example.com (Plan: Free)
Version                       3.5.0
Region                        United States (us)
Forwarding                    https://abc123.ngrok.io -> http://localhost:3000

Sua API agora está acessível em https://abc123.ngrok.io.

Passo 4: Teste

curl https://abc123.ngrok.io/health
# {"status":"healthy"}

Opção 2: Usando NPort (Alternativa Gratuita)

Passo 1: Instale o NPort

npm install -g nport-cli
# or
curl -sSL https://nport.io/install.sh | bash

Passo 2: Inicie o túnel

nport start 3000 --subdomain myapi

Saída:

✓ Tunnel started successfully
Public URL: https://myapi.nport.io
Local URL:  http://localhost:3000

Passo 3: Teste

curl https://myapi.nport.io/health
# {"status":"healthy"}

Opção 3: Usando Cloudflare Tunnel

Passo 1: Instale o cloudflared

# macOS
brew install cloudflare/cloudflare/cloudflared

# Linux
wget -q https://github.com/cloudflare/cloudflared/releases/latest/download/cloudflared-linux-amd64.deb
sudo dpkg -i cloudflared-linux-amd64.deb

Passo 2: Túnel rápido (sem necessidade de cadastro)

cloudflared tunnel --url http://localhost:3000

Saída:

2026-01-27T12:00:00Z INF Your quick tunnel is: https://xyz789.trycloudflare.com

Para túneis persistentes (requer conta Cloudflare):

# Login
cloudflared tunnel login

# Create tunnel
cloudflared tunnel create myapi

# Configure and run
cloudflared tunnel --config config.yml run myapi

Testando Webhooks com Apidog

Agora que seu localhost está publicamente acessível, vamos testar webhooks sistematicamente usando Apidog.

Por Que Combinar Tunelamento + Apidog?

O tunelamento resolve o acesso; o Apidog resolve a verificação:

Configurando o Teste de Webhook no Apidog

Passo 1: Importe ou Crie Sua API

  1. Abra o Apidog

2. Crie um novo projeto

3. Adicione seu endpoint de webhook:

Passo 2: Configure Variáveis de Ambiente

Configure dois ambientes:

Desenvolvimento (Tunelado):

{
  "base_url": "https://abc123.ngrok.io"
}

Produção:

{
  "base_url": "https://api.yourapp.com"
}

Isso permite que você teste o mesmo endpoint localmente e em produção com um clique.

Passo 3: Crie Cenários de Teste

Teste o que acontece quando os webhooks chegam:

Exemplo: Teste de Webhook de Pagamento do Stripe

// Request Body
{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "id": "pi_test123",
      "amount": 2000,
      "currency": "usd",
      "status": "succeeded"
    }
  }
}

Asserções no Apidog:

  1. Código de status igual a 200
  2. Resposta contém received: true
  3. Tempo de resposta < 1000ms
  4. Content-Type é application/json

Passo 4: Simule Serviços de Terceiros

Em vez de acionar webhooks reais do Stripe ou GitHub, simule-os no Apidog:

  1. Copie exemplos de payload de webhook da documentação do serviço
  2. Crie casos de teste com vários cenários (sucesso, falha, casos extremos)
  3. Execute todos os cenários contra seu localhost tunelado
  4. Verifique se sua API lida com cada caso corretamente

Testando Callbacks OAuth

Cenário: Você está implementando "Fazer login com o Google"

Passo 1: Inicie o túnel com subdomínio personalizado

ngrok http 3000 --subdomain myapp
# URL: https://myapp.ngrok.io

Passo 2: Configure o redirecionamento OAuth no Console do Google

Defina a URL de callback: https://myapp.ngrok.io/auth/google/callback

Passo 3: Teste o fluxo no Apidog

  1. Faça uma requisição para /auth/google para obter a URL de autorização
  2. Siga o redirecionamento manual ou programaticamente
  3. Verifique se o callback recebe o código de autorização
  4. Afirme que a troca de token funciona corretamente

Passo 4: Valide o armazenamento do token

Use o Apidog para:

Casos de Uso Comuns

1. Testando Webhooks de Pagamento (Stripe, PayPal)

Desafio: Provedores de pagamento enviam webhooks para eventos como cobranças bem-sucedidas, reembolsos, disputas.

Solução:

# Inicie o túnel
ngrok http 3000

# Configure a URL do webhook no painel do Stripe
# https://abc123.ngrok.io/webhook/stripe

# Use a CLI do Stripe para encaminhar webhooks de teste
stripe listen --forward-to localhost:3000/webhook/stripe

# Acione eventos de teste
stripe trigger payment_intent.succeeded

Teste com Apidog:

2. Testando Comandos de Bot do Slack/Discord

Desafio: Plataformas de bate-papo enviam eventos de interação quando os usuários clicam em botões ou executam comandos.

Solução:

# Inicie o túnel
nport start 3000 --subdomain myslackbot

# Configure na API do Slack:
# URL de Interatividade: https://myslackbot.nport.io/slack/interactions
# Comandos de Barra: https://myslackbot.nport.io/slack/commands

Teste com Apidog:

3. Testando Webhooks de SMS/Voz (Twilio)

Desafio: O Twilio envia webhooks quando um SMS chega ou chamadas de voz são recebidas.

Solução:

cloudflared tunnel --url http://localhost:3000

Configure os webhooks TwiML para apontar para a URL do seu túnel.

Teste com Apidog:

4. Teste de API para Aplicativos Móveis

Desafio: Testar sua API a partir de um dispositivo físico ou emulador.

Problema com localhost:

// Isso falha a partir de um dispositivo móvel
fetch('http://localhost:3000/api/users')

Solução com túnel:

// Isso funciona de qualquer lugar
fetch('https://myapi.ngrok.io/api/users')

Teste com Apidog:

  1. Gere a documentação da API com a URL base tunelada
  2. Compartilhe com a equipe móvel
  3. Desenvolvedores móveis podem testar contra seu servidor de desenvolvimento ativo
  4. Mude para URLs de staging/produção quando pronto

5. Testando Webhooks do GitHub/GitLab

Desafio: Testar webhooks de repositório (push, pull request, issues) localmente.

Solução:

# Inicie o túnel
ngrok http 4000

# Configure nas configurações do repositório GitHub:
# URL do Webhook: https://abc123.ngrok.io/github/webhook
# Tipo de conteúdo: application/json
# Eventos: Push, Pull requests

Teste com Apidog:

Melhores Práticas de Segurança

Expor o localhost à internet cria riscos de segurança. Siga estas práticas:

1. Use Apenas HTTPS

Todos os serviços de tunelamento fornecem HTTPS por padrão. Nunca use HTTP puro para túneis:

# Bom
ngrok http 3000
# Cria https://abc123.ngrok.io

# Ruim (não faça isso)
ngrok http --scheme=http 3000

2. Implemente a Verificação de Assinatura de Webhook

Não confie cegamente nos webhooks de entrada. Verifique as assinaturas:

const crypto = require('crypto');

function verifyStripeSignature(payload, signature, secret) {
  const expectedSignature = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
}

app.post('/webhook/stripe', (req, res) => {
  const signature = req.headers['stripe-signature'];

  if (!verifyStripeSignature(req.body, signature, process.env.STRIPE_SECRET)) {
    return res.status(401).send('Invalid signature');
  }

  // Processe o webhook
});

3. Restrinja o Acesso com Autenticação Básica

Adicione autenticação ao seu túnel:

# ngrok com autenticação básica
ngrok http 3000 --auth="username:password"

# NPort com autenticação básica
nport start 3000 --auth username:password

Agora as requisições precisam de credenciais:

curl -u username:password https://abc123.ngrok.io/webhook

4. Use Segredos Específicos do Ambiente

Nunca comite segredos de webhook ou chaves de API:

// .env.development
STRIPE_WEBHOOK_SECRET=whsec_test_abc123
WEBHOOK_TUNNEL_URL=https://abc123.ngrok.io

// .env.production
STR

Pratique o design de API no Apidog

Descubra uma forma mais fácil de construir e usar APIs

Cadastre-se gratuitamenteBaixar