Como usar o comando curl para testar se uma API ou webhook está respondendo

Testando uma API ou Webhook com o comando curl

Olá! Aqui é a Sensei da GeHost 🥋. Hoje vamos aprender uma ferramenta simples, mas poderosíssima, para quem trabalha com integrações, automações ou sistemas que "conversam" entre si: o curl.

Se você já configurou um webhook (por exemplo, para receber notificações de pagamento, formulário ou pedido) e quer ter certeza de que o endereço está realmente respondendo, o curl é o jeito mais rápido e confiável de verificar isso — sem precisar instalar nenhum programa extra, direto pelo terminal.

Não se preocupe se você nunca usou um terminal antes. Vamos passo a passo, com calma. 💛

O que é o curl, afinal?

Pense no curl como um "mensageiro" que você manda até um endereço na internet (uma URL) para perguntar: "ei, você está aí? Está funcionando?". Ele então volta com a resposta — e essa resposta nos diz muita coisa: se o servidor está de pé, se a URL está certa, se há algum erro de permissão, etc.

É uma ferramenta padrão em sistemas Linux (como o ambiente por trás da sua hospedagem) e também está disponível no Mac e no Windows.

Passo 1 — Acesse o terminal

Você pode testar o curl de duas formas:

• Pelo seu computador: no Mac ou Linux, abra o aplicativo "Terminal". No Windows, abra o "PowerShell" ou "Prompt de Comando".
• Via SSH na sua hospedagem: se você tem acesso SSH liberado no seu plano, pode conectar ao seu servidor e rodar o comando por lá. Caso não saiba como acessar via SSH, nosso time de suporte pode te orientar durante o período de suporte gratuito, ou você confere as instruções no painel.gehost.com.br.

Passo 2 — O teste mais simples (requisição GET)

Para verificar se um endereço está respondendo, digite:

curl -I https://exemplo.com/sua-api

O parâmetro -I (letra "i" maiúscula) pede apenas os cabeçalhos da resposta, sem baixar o conteúdo todo — é rápido e ótimo para um primeiro diagnóstico.

Você vai ver algo parecido com isto:

HTTP/1.1 200 OK
Content-Type: application/json
...

O que significa o número que aparece?

Esse número é o código de status HTTP — a "nota" que o servidor te dá sobre como foi a requisição. Os mais comuns:

• 200 OK — tudo certo, o endereço está respondendo normalmente. ✅
• 301 / 302 — o endereço está redirecionando para outra URL (não é necessariamente um erro).
• 404 Not Found — o endereço não existe ou está digitado errado.
• 401 / 403 — falta autenticação ou permissão para acessar.
• 500 / 502 / 503 — algo deu errado do lado do servidor que está recebendo a requisição.

Passo 3 — Testando um webhook (requisição POST)

A maioria dos webhooks espera receber dados via POST, não um simples GET. Para simular isso, use:

curl -X POST https://exemplo.com/webhook \
  -H "Content-Type: application/json" \
  -d '{"teste": "ola"}'

Explicando cada parte:

• -X POST — diz ao curl para enviar uma requisição do tipo POST.
• -H "Content-Type: application/json" — avisa que estamos enviando dados em formato JSON.
• -d '{"teste": "ola"}' — é o conteúdo (corpo) que está sendo enviado, como se fosse o "recado" da notificação.

Dica da Sensei: ajuste o conteúdo do -d conforme o formato que o seu webhook realmente espera receber. Se não tiver certeza, consulte a documentação do serviço que vai receber essa notificação.

Passo 4 — Modo detalhado, para investigar problemas

Se algo não estiver funcionando como esperado, use o parâmetro -v (verbose) para ver cada detalhe da conversa entre o curl e o servidor:

curl -v https://exemplo.com/sua-api

Ele mostra desde a conexão sendo aberta até os cabeçalhos enviados e recebidos — muito útil para descobrir, por exemplo, se o problema é de SSL, de DNS ou de permissão.

Passo 5 — Medindo o tempo de resposta

Quer saber quanto tempo o endereço demorou para responder? Use:

curl -o /dev/null -s -w "Tempo total: %{time_total}s\n" https://exemplo.com/sua-api

Esse comando não mostra o conteúdo da resposta (-o /dev/null), fica em modo silencioso (-s) e no final exibe só o tempo total gasto.

Resumo rápido

1. Abra o terminal (no seu computador ou via SSH na hospedagem).
2. Use curl -I para um teste rápido de status.
3. Use curl -X POST com -H e -d para simular o envio de um webhook.
4. Use -v quando precisar investigar um erro com mais detalhes.
5. Confira sempre o código de status retornado (200 é o que você quer ver!).

Se mesmo seguindo os passos você continuar recebendo erro e não conseguir identificar a causa, pode contar com o nosso suporte durante os 30 dias gratuitos após a entrega do seu serviço, ou acessar mais informações pelo painel.gehost.com.br. Estamos por aqui torcendo pelo seu sucesso! 🌱