O teste local de webhooks do Stripe permite validar os handlers de eventos de pagamento na sua máquina antes de subir para produção. Você executa seu app localmente, expõe-no por uma URL HTTPS pública e recebe eventos reais do Stripe em modo de teste com a verificação de assinatura totalmente preservada.
Por que os webhooks do Stripe precisam de uma URL pública
O Stripe entrega eventos de webhook pela internet pública a uma URL de endpoint configurada. Endereços como 127.0.0.1:3000 são inacessíveis a partir dos servidores do Stripe, então o desenvolvimento local exige uma ponte. Um túnel para localhost mapeia uma URL HTTPS pública para o seu processo local sem mudanças no roteador ou firewall.
O que você precisa antes de testar
- Uma conta Stripe em modo de teste.
- Um app local com uma rota de webhook (por exemplo
/api/webhooks/stripe). - O segredo de assinatura do webhook do Stripe configurado em variáveis de ambiente.
- Uma ferramenta de túnel que preserve os cabeçalhos da requisição para a verificação de assinatura.
Passo a passo: testar webhooks do Stripe localmente com o PortPreview
- Inicie sua aplicação localmente na porta desejada.
- Execute
npx portpreview 3000para gerar uma URL HTTPS pública. - No Dashboard do Stripe, vá em Desenvolvedores → Webhooks e adicione a URL do túnel mais o caminho do seu webhook.
- Selecione os eventos que deseja testar (por exemplo
checkout.session.completed,invoice.paid). - Dispare eventos de teste pelo Dashboard ou pela CLI do Stripe e inspecione cada entrega.
- Verifique se o handler retorna uma resposta 2xx e se a validação de assinatura passa.
O PortPreview captura cabeçalhos, corpo e status da resposta para que você depure entregas falhas sem adivinhar apenas pelos logs do servidor.
Validar assinaturas de webhook do Stripe localmente
Nunca desative a verificação de assinatura durante o desenvolvimento. O Stripe assina cada payload com o seu segredo de webhook, e o handler deve validar o cabeçalho Stripe-Signature exatamente como em produção. Ferramentas de túnel que preservam os cabeçalhos originais permitem testar o caminho real do código.
Falhas de assinatura comuns durante o teste local:
- Usar o segredo de webhook errado (segredo do Dashboard vs. segredo da CLI).
- Ler um corpo JSON já parseado antes da verificação em vez do corpo bruto da requisição.
- Diferença de relógio além da janela de tolerância do Stripe.
Eventos que vale a pena testar localmente
Checkout e assinaturas
Teste checkout.session.completed, customer.subscription.created e invoice.payment_failed para confirmar provisionamento, concessão de acesso e a lógica de cobrança em atraso.
Fluxos de Connect e marketplace
Se você usa o Stripe Connect, valide eventos de atualização de conta e notificações de transferência com contas conectadas de teste antes de ir ao ar.
Idempotência e retentativas
O Stripe repete entregas que falham. Use o replay de webhook para confirmar que o handler processa eventos duplicados com segurança.
Stripe CLI vs. túnel para localhost
A CLI do Stripe pode encaminhar eventos com stripe listen --forward-to, o que funciona bem para verificações rápidas. Um túnel para localhost oferece uma URL pública estável que você cola no Dashboard, compartilha com colegas e usa em vários provedores — não só no Stripe. Muitas equipes usam ambos: a CLI para iteração rápida e túneis para testes de integração que espelham a configuração de produção.
Quando passar do local para o staging
O teste local cobre a lógica do handler, o parse do payload e a validação de assinatura. Passe para o staging para verificações específicas do ambiente, como segredos gerenciados, migrações de banco e pipelines de release de ponta a ponta. No dia a dia de funcionalidades de pagamento, o teste local de webhooks do Stripe reduz a iteração de minutos para segundos.
Leia nosso guia completo sobre depurar webhooks localmente ou entre na lista de espera do PortPreview para fluxos de túnel focados em webhooks.