Testar um webhook Stripe localmente
Integrar webhooks da Stripe muitas vezes obriga a disparar pagamentos reais em modo de teste só para validar o handler. Com o Webhook Toolkit, gere um evento Stripe assinado e válido em um clique, edite o payload e envie direto para o seu endpoint local. Sua verificação de Stripe-Signature é testada na hora.
Verificar a assinatura no servidor
No lado Node.js, seu handler precisa validar o header antes de processar o evento:
const sig = req.headers['stripe-signature'];
const event = stripe.webhooks.constructEvent(
rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET
);
if (event.type === 'payment_intent.succeeded') {
// ...
}Lembre de passar o raw body (não parseado) para o constructEvent, senão a assinatura nunca vai bater. Para receber um evento real da Stripe no seu localhost, crie um túnel Relay.
Recebendo signature verification failed em vez de um 200 limpo? O validador de assinatura da Stripe recalcula o HMAC a partir do seu whsec, do corpo bruto e do cabeçalho Stripe-Signature e aponta a causa exata.
Perguntas frequentes
Como testar um webhook Stripe localmente sem pagamento real?
Use o gerador acima: escolha o evento (ex.: payment_intent.succeeded), cole o seu signing secret whsec_…, informe a URL do seu handler local (via Relay ou um endpoint do Receiver) e clique em Assinar & enviar. O header Stripe-Signature é calculado exatamente como a Stripe faz.
O header Stripe-Signature gerado é válido?
Sim. Ele segue o esquema oficial t=timestamp,v1=HMAC_SHA256(timestamp.payload, secret). O stripe.webhooks.constructEvent() vai validar sem erro desde que você use o signing secret correto.
Posso alterar o valor ou o customer?
Sim, o payload é totalmente editável antes do envio. Mude o valor, o customer ID, o status… e reenvie quantas vezes precisar.
Qual a diferença para a CLI da Stripe?
A CLI da Stripe só funciona com a Stripe e exige instalação. O Webhook Toolkit também cobre GitHub, Slack, Twilio, Mailgun e Shopify, no navegador, e ainda captura/inspeciona as requisições recebidas.