Para testar um webhook, você fornece ao provedor uma URL acessível, dispara um evento real e, em seguida, confirma que seu manipulador aceita o payload e reage corretamente. A parte difícil é que seu aplicativo é o receptor, não o chamador, então você não pode simplesmente clicar em “Enviar” e ler a resposta. Este guia descreve as ferramentas que você precisa (serviços de inspeção, túneis locais, gatilhos de provedor) e um processo repetível para validar seu manipulador de ponta a ponta.
Por que webhooks são mais difíceis de testar do que APIs normais
Com uma chamada de API normal, você controla a requisição. Você escolhe o método, define o corpo, dispara e lê a resposta. Webhooks invertem isso. O provedor envia a requisição para você, em seu próprio cronograma, com um payload que ele define. Essa inversão de papéis cria quatro problemas de teste.
Primeiro, você não pode disparar o evento sozinho por padrão. Um evento payment_intent.succeeded só é disparado quando o Stripe decide que aconteceu, então você precisa de ferramentas do provedor para forçar um.
Segundo, a entrega é assíncrona. O evento chega quando a ação upstream é concluída, então seu teste precisa capturar uma requisição de entrada em vez de bloquear um valor de retorno.
Terceiro, o formato do payload é definido pelo provedor. Seu manipulador precisa analisar exatamente o que GitHub, Stripe ou Slack enviam.
Quarto, a maioria dos provedores assina suas requisições. Seu endpoint deve verificar um cabeçalho de assinatura antes de confiar no corpo, e um teste que ignora isso esconde bugs reais. Para uma análise mais aprofundada, consulte nosso guia sobre verificação de assinatura de webhook.
Se você ainda está decidindo se webhooks são o padrão certo para sua integração, webhooks vs polling e webhook vs WebSocket comparam as vantagens e desvantagens.
O kit de ferramentas de teste de webhook
Você usará quatro tipos de ferramentas, muitas vezes na mesma sessão: um serviço de captura para ver payloads brutos, um túnel para acessar seu laptop, gatilhos de provedor para disparar eventos reais e uma ferramenta de asserção para verificar seu manipulador.
1. Serviços de inspeção e captura
Antes de escrever uma única linha de código do manipulador, aponte o provedor para uma URL temporária e veja o que ele realmente envia. Esses serviços fornecem um endpoint público e mostram todas as requisições em tempo real.
webhook.site oferece uma URL aleatória única e um endereço de e-mail no momento em que a página é carregada. Tudo o que é enviado aparece instantaneamente: corpo completo, cabeçalhos e método. As URLs gratuitas expiram após 7 dias e têm um limite de 100 requisições, com um tamanho máximo de requisição de 10 MB. Planos pagos adicionam URLs permanentes, requisições ilimitadas e um histórico retido das últimas 10.000 requisições.
Beeceptor oferece um endpoint HTTPS gratuito que você pode usar como receptor de webhook e inspecionar payloads de entrada em tempo real. Ele também fornece endpoints de mock server, para que você possa capturar e simular com a mesma ferramenta.
Pipedream RequestBin é outra ferramenta de captura de requisições amplamente utilizada. Verifique sua documentação atual para especificações de nível, já que os serviços de captura mudam seus limites gratuitos frequentemente.
Use-os para responder a uma pergunta: qual é a aparência do payload real? Copie uma amostra para mais tarde, quando você construir testes repetíveis.
2. Desenvolvimento local: exponha o localhost com um túnel
Os provedores não conseguem acessar localhost:3000 em sua máquina. Um túnel cria uma URL HTTPS pública que encaminha o tráfego para sua porta local, permitindo que você execute seu manipulador em seu editor e o depure ao vivo.
ngrok é a escolha comum. Instale-o, autentique-se uma vez e, em seguida, encaminhe uma porta.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # encaminha uma URL HTTPS pública para localhost:3000
Contas gratuitas do ngrok recebem um domínio de desenvolvimento escolhido automaticamente. Domínios personalizados exigem um plano pago.
cloudflared executa um túnel rápido com um único comando se você preferir o Cloudflare.
cloudflared tunnel --url http://localhost:3000
Cole a URL pública que o túnel imprime nas configurações de webhook do provedor, e os eventos de entrada cairão em seu servidor local. Para uma explicação mais completa desse padrão, veja como testar APIs localhost com serviços de webhook.
3. Disparando eventos de teste do provedor
Uma URL de captura só ajuda depois que algo é enviado a ela. A maioria dos principais provedores oferece ferramentas para disparar eventos de teste sob demanda, para que você não precise fabricar pagamentos ou pushes reais.
Stripe CLI é o exemplo mais claro. O comando stripe listen encaminha eventos ao vivo da sua sandbox do Stripe para um caminho local e imprime um segredo de assinatura de webhook que você coloca na configuração do seu aplicativo.
# Encaminhar todos os eventos para o seu manipulador local:
stripe listen --forward-to localhost:3000/webhooks
# Filtrar para eventos específicos apenas:
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Com o listener em execução, stripe trigger dispara um evento de teste. Observe que o disparo cria objetos de API devidamente suportados e tem efeitos colaterais: payment_intent.succeeded também emite payment_intent.created.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # listar todos os eventos suportados
O GitHub mantém um breve histórico de entrega que você pode reproduzir. Vá para seu repositório, depois Configurações, depois Webhooks em “Código e automação”. Clique na URL do webhook, abra a aba “Entregas Recentes”, clique em um GUID de entrega e clique em “Reentregar”. Duas restrições importam: você só pode reentregar entregas dos últimos 3 dias, e você precisa de acesso de administrador ao repositório. O GitHub não reentrega automaticamente as entregas falhas, então a reprodução é manual.
Os webhooks de entrada do Slack são os mais simples de testar. Você envia uma mensagem POSTando JSON para a URL do webhook. O payload mínimo é apenas um campo text.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
A URL do webhook do Slack é um segredo. O Slack revoga URLs que vazam, então mantenha-a fora do código do lado do cliente e de repositórios públicos.
4. Validando seu manipulador
Capturar e disparar provam que a tubulação funciona. Eles não provam que seu manipulador está correto. A ferramenta final envia um payload customizado e verifica a resposta, além dos efeitos colaterais. Na sua forma mais básica, isso é um comando curl com um corpo representativo.
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"}}}'
Um único curl é bom para um teste de fumaça. Ele falha quando você deseja testes repetíveis e validados que rodam em CI. É aí que uma ferramenta de API dedicada ganha seu lugar.
Testando webhooks com Apidog
Apidog é uma plataforma de API tudo-em-um para projetar, depurar, testar, simular e documentar APIs. Ele não possui uma “caixa de entrada de webhook” dedicada, então esta seção é honesta sobre o que ele realmente faz bem: criar payloads, salvá-los, validar respostas e atuar como um provedor com um mock server.
Crie e salve um payload de amostra como uma requisição reutilizável
Pegue o payload que você capturou do webhook.site (ou copiou da documentação de um provedor) e construa-o em uma requisição Apidog. Defina o método como POST, cole o corpo JSON e adicione os cabeçalhos que o provedor envia, incluindo o cabeçalho de assinatura que seu manipulador verifica.
Salve essa requisição contra seu endpoint. Agora você tem uma maneira repetível e controlada por versão para POSTar um payload conhecido e válido (ou propositalmente malformado) para seu manipulador, em vez de redigitar um comando curl toda vez.
Valide a resposta com o construtor visual de asserções
Enviar o payload é metade do teste. A outra metade é verificar o que seu manipulador retorna. Na etapa de requisição ou cenário, abra Processadores Pós-execução, clique em “+ Adicionar” e escolha “Asserção”. O Apidog adiciona uma regra de validação que você configura sem código.
Aponte a asserção para o corpo da resposta e use $ para a raiz JSON. Por exemplo, direcione $.data.status, defina a condição como Igual a, e compare com succeeded. Execute a requisição, e o resultado será mostrado na aba Asserção. Asserções visuais comparam valores como strings. Quando você precisar de verificações precisas de tipo (um número real, um booleano), mude para um script personalizado usando a sintaxe pm.test compatível com Postman.
Isso transforma "ele retornou um 200" em "ele retornou um 200, o campo de status é 'succeeded' e o ID do pedido corresponde". Construa várias asserções em um cenário para cobrir o caminho de sucesso, um caso de campo ausente e uma rejeição de assinatura inválida.
Use um mock server para simular o provedor
Às vezes você quer testar a outra direção: um serviço em sua stack que chama um provedor. Durante o teste local, você pode não querer realmente atingir o provedor. O mock server do Apidog permite que você o simule.
O Apidog oferece três tipos de mock. O Mock Local executa com o cliente desktop e funciona apenas enquanto o cliente está aberto. O Mock na Nuvem é hospedado nos servidores do Apidog, funciona 24 horas por dia, 7 dias por semana, e pode ser ativado ou desativado (está desativado por padrão). O Mock Runner executa em infraestrutura de runner auto-hospedada e é compartilhado em sua equipe. Cada endpoint HTTP tem um módulo de Mock; copie a URL do mock da aba API no modo Design ou da aba Mock no modo Debug. Apenas caminhos que começam com / roteiam para o ambiente de mock. Aponte seu código para essa URL de mock durante os testes, e sua integração obterá respostas previsíveis do provedor sem chamadas reais de API ou efeitos colaterais.
Execute testes de webhook em CI com o Apidog CLI
Assim que seu cenário for aprovado localmente, execute-o a cada push com o Apidog CLI. Ele requer Node.js v16 ou superior.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # verificar a instalação
Execute um cenário salvo online, passando o token de acesso e os IDs da aba “Linha de comando” de CI/CD do cenário.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Aqui -t é o cenário de teste, -e é o ambiente (obrigatório), -d são os dados de teste (um caminho de arquivo CSV ou JSON, ou um ID de conjunto de dados armazenado), e -r define os reporters, que aceitam cli, html, json e junit. Para uma explicação completa da linha de comando, consulte o tutorial do Apidog CLI.
Quer construir e validar seus próprios testes de webhook visualmente? Experimente o Apidog gratuitamente, sem necessidade de cartão de crédito.
Um fluxo de trabalho de teste de webhook passo a passo
Juntando as ferramentas, aqui está uma sequência repetível.
- Inspecione o payload real. Aponte o provedor para uma URL do webhook.site e capture um evento real. Observe o formato do corpo, os cabeçalhos e o formato da assinatura.
- Alcance seu código. Inicie seu manipulador localmente, abra um túnel com
ngrok http 3000oucloudflared, e coloque a URL pública na configuração do webhook do provedor. - Dispare um evento real. Use
stripe trigger, o botão Redeliver do GitHub ou um POST do Slack para enviar um evento genuíno através do túnel. - Verifique o tratamento da assinatura. Envie o mesmo payload com uma assinatura válida e novamente com uma adulterada. Seu manipulador deve aceitar o primeiro e rejeitar o segundo.
- Valide a resposta e os efeitos colaterais. Salve o payload como uma requisição Apidog, adicione asserções no corpo e status da resposta, e confirme se a linha do banco de dados ou a chamada downstream ocorreu.
- Automatize. Mova o cenário para o Apidog CLI para que ele seja executado em CI a cada alteração.
Se você está projetando o próprio sistema de webhook em vez de apenas consumir um, como projetar webhooks confiáveis e melhores práticas de webhook de pagamento cobrem retentativas, idempotência e segurança. Para uma visão mais ampla, o guia da API de webhooks e webhooks e arquitetura orientada a eventos explicam onde os webhooks se encaixam em um sistema maior.
Perguntas Frequentes
Como você testa um webhook?
Forneça ao provedor uma URL acessível, dispare um evento real ou de teste, então confirme que seu manipulador recebe o payload, verifica a assinatura, retorna o status correto e executa o efeito colateral esperado. Capture um payload real primeiro, então construa uma requisição repetível com asserções para que o teste seja executado da mesma forma sempre.
Como você testa webhooks localmente?
Execute seu manipulador em uma porta local, então exponha-o com um túnel para que o provedor possa alcançar sua máquina. Use ngrok http 3000 ou cloudflared tunnel --url http://localhost:3000, cole a URL HTTPS pública nas configurações de webhook do provedor e dispare um evento. Requisições de entrada chegarão ao seu servidor local, onde você pode definir pontos de interrupção e inspecioná-las ao vivo.
Como você testa um webhook com o Postman?
O Postman pode POSTar um payload personalizado para seu endpoint e validar a resposta, mas ele não pode receber um webhook de entrada real por si só. O mesmo se aplica ao Apidog: você constrói uma requisição com o payload e os cabeçalhos do provedor, adiciona asserções ao corpo e status da resposta, e a salva como um teste reutilizável. Para capturar um evento de entrada genuíno, emparelhe a ferramenta com um serviço de captura ou um túnel.
Como você testa webhooks do Stripe?
Use o Stripe CLI. Execute stripe listen --forward-to localhost:3000/webhooks para encaminhar eventos da sandbox para seu manipulador e obter um segredo de assinatura. Em seguida, execute stripe trigger payment_intent.succeeded (ou qualquer evento de stripe trigger --help) para disparar um evento de teste real. O disparo cria objetos de API com suporte e pode cascatear, então payment_intent.succeeded também emite payment_intent.created.
Como você testa um webhook do Slack?
POSTe JSON para a URL de webhook de entrada. O payload mínimo válido é {"text":"Hello, world."}, enviado com um cabeçalho Content-type: application/json. Um teste bem-sucedido posta a mensagem no canal configurado. Mantenha a URL em segredo, já que o Slack revoga URLs de webhook que vazam.
Como você testa uma URL de webhook?
Envie um POST de amostra para a URL e confirme se ela retorna um status de sucesso e se comporta corretamente. A verificação mais rápida é um único curl com um corpo representativo. Para um teste real, capture um payload real primeiro, envie-o com assinaturas válidas e inválidas, e valide a resposta e os efeitos colaterais em vez de apenas verificar se há um 200.