Replay de webhook: depurar sem disparar de novo

O replay de webhook reenvia um callback HTTP capturado anteriormente ao seu handler local, sem pedir ao provedor upstream que entregue o evento de novo. Em vez de disparar novamente uma cobrança do Stripe, um push do GitHub ou uma mensagem do Twilio, você reproduz a requisição exata — cabeçalhos, corpo e tudo — a partir do seu histórico de requisições.

Por que o replay de webhook importa

A depuração de webhooks costuma seguir um ciclo cansativo: disparar um evento, inspecionar a entrega, achar um bug, corrigir o código, disparar de novo. Disparar eventos upstream novamente é lento, ruidoso e às vezes impossível (eventos de pagamento únicos, recursos excluídos ou APIs de teste com limite de taxa).

O replay encurta esse ciclo. Capture uma vez, corrija o handler e reproduza o mesmo payload até passar — tudo sem tocar no provedor externo.

Como o replay de webhook funciona

1. Um callback chega à sua URL de túnel e é encaminhado ao seu app local.
2. A ferramenta de túnel captura a requisição completa: método, caminho, cabeçalhos e corpo.
3. Você corrige o código do handler com base no que vê na requisição capturada.
4. Você reproduz a requisição capturada para o seu endpoint local com uma ação.
5. Repita até o handler retornar a resposta correta.

Esse fluxo exige um túnel para localhost com captura de requisições embutida — não apenas encaminhamento de tráfego.

Casos de uso do replay de webhook

Desenvolvimento de handler

Construa e teste handlers de webhook de forma iterativa. Reproduza o mesmo evento checkout.session.completed do Stripe dez vezes enquanto refina a lógica de parse.

Testes de idempotência

Os provedores entregam eventos duplicados durante as retentativas. Reproduza o mesmo payload várias vezes para confirmar que seu handler processa duplicatas com segurança, sem cobranças em dobro ou registros repetidos.

Depuração da verificação de assinatura

Quando as checagens de assinatura falham, reproduza a requisição original com os cabeçalhos intactos para isolar se o problema está na lógica de verificação ou no parse do payload.

Testes de regressão

Salve requisições capturadas de eventos de teste próximos da produção e reproduza-as após refatorações para detectar mudanças que quebram antes do deploy.

Replay de webhook com o PortPreview

1. Inicie seu app e execute npx portpreview 3000.
2. Configure seu provedor para enviar callbacks à URL do túnel.
3. Dispare um evento de teste e inspecione a requisição capturada no PortPreview.
4. Corrija seu handler e então reproduza a requisição capturada.
5. Verifique o status e o corpo da resposta sem disparar o provedor de novo.

O PortPreview preserva os cabeçalhos originais, então a verificação de assinatura do provedor continua significativa durante o replay.

Replay vs. disparar de novo: quando usar cada um

• Replay: bugs de lógica do handler, parse de payload, checagens de idempotência, depuração de assinaturas.
• Disparar de novo: testar a geração de eventos do lado do provedor, verificar o registro do webhook ou a integração de ponta a ponta com o estado real do provedor.

Para a configuração específica de cada provedor, veja os guias sobre testar webhooks do Stripe localmente, testar webhooks do GitHub localmente e testar webhooks do Twilio localmente.

Boas práticas para o replay de webhook

• Sempre valide as assinaturas durante o replay, não apenas na primeira entrega.
• Teste a entrega duplicada reproduzindo o mesmo evento várias vezes.
• Mantenha o histórico de requisições durante as branches de feature para checagens de regressão.
• Use credenciais em modo de teste para que os eventos reproduzidos nunca afetem os dados de produção.

Entre na lista de espera do PortPreview para ter captura e replay de webhooks embutidos no seu fluxo de túnel.