O ngrok é a ferramenta que eu pego 30 segundos depois de começar a integrar qualquer provedor de webhooks. Você roda o comando ngrok http 3000, cola a URL pública no Dashboard da Stripe e, em um minuto, já está parando em breakpoints no seu handler local. É um ganho óbvio na velocidade do ciclo de desenvolvimento.
O problema é que o ngrok continua sendo usado em contextos para os quais nunca foi pensado: ambientes de homologação (staging), túneis "temporários" em produção, depuração de quedas em produção. É aí que as equipes queimam horas. Este texto é sobre onde termina o trabalho do ngrok e do que você realmente precisa depois disso.
TL;DR
- O ngrok é a ferramenta certa para desenvolvimento local, e nada o supera ali. Continue usando.
- É a ferramenta errada para qualquer coisa que precise sobreviver a um notebook fechado: homologação, produção, sessões longas de depuração, auditoria, recuperação de quedas
- Além do desenvolvimento local, você quer persistência, replay (um novo envio de um evento armazenado, feito por você) e o envio do mesmo evento para vários destinos, que é o que um relay de webhooks (um serviço que recebe, guarda e encaminha seus webhooks) oferece
- O padrão que funciona é ngrok e um relay, não um ou outro
No que o ngrok é ótimo
Testar o segredo de assinatura localmente, para começar. O único jeito de exercitar a verificação de assinatura é receber de fato uma requisição assinada, e o ngrok permite isso.
Testar caminhos de falha, também. Responda 500 no seu handler, veja o Dashboard da Stripe marcar a entrega como falha e confira sua lógica de novas tentativas (retries).
Também é o jeito mais rápido de ver exatamente os cabeçalhos que um provedor envia, inclusive os estranhos. E, para demos descartáveis, quando você quer mostrar a integração funcionando para alguém da equipe, você abre um ngrok por 20 minutos e segue em frente.
Para isso, ele é perfeito. Continue usando.
Onde o ngrok deixa de bastar
Ambientes de homologação. Você não quer que a homologação dependa de um túnel no notebook de alguém, e um túnel morre quando o notebook entra em repouso. A homologação vira "quem configurou o webhook por último", que é uma dependência compartilhada do uptime de uma única pessoa.
Produção. Obviamente.
Sessões longas de depuração. Se você precisa de 3 dias de captura de webhooks para reproduzir um bug que acontece uma vez por dia, o plano gratuito do ngrok guarda só 24 horas de tráfego. O plano pago resolve, mas aí você está pagando um túnel para fazer log, o que é o formato errado.
Passar o bastão para o suporte ou para colegas que não são devs. Eles precisam de uma URL que funcione sem "deixa eu abrir o ngrok primeiro".
Auditabilidade. Se a equipe de compliance pedir "mostre todos os eventos de webhook que recebemos no 1º trimestre", o ngrok não tem nada para você.
Recuperação de quedas. Se seu servidor ficou fora do ar e a janela de novas tentativas da Stripe expirou, o ngrok não tem os eventos.
Do que você precisa além do túnel
Quando você passa do "só quero fazer um POST no localhost", o formato real do problema é:
- Uma URL pública estável que não depende de nenhum notebook
- Persistência, para que cada evento recebido fique armazenado e possa ser lido depois
- Entrega para vários destinos: localhost para desenvolvimento, homologação para alguém da equipe, produção para o tráfego real, tudo a partir de uma única URL de entrada
- Replay, no sentido de "envie de novo para o meu handler aquele evento de ontem"
- Novas tentativas e alertas, para que um endpoint instável receba novas tentativas e você fique sabendo
É outra categoria de ferramenta. Chame de relay de webhooks ou de proxy de webhooks, dependendo de para quem você pergunta.
Onde os relays de webhooks entram
Um relay fica entre o provedor e seus endpoints. Os provedores enviam para uma URL estável (in.anyhook.net/you/stripe), e o relay cuida da entrega, das novas tentativas, do log e do replay.
No desenvolvimento local, você adiciona a URL do seu túnel como destino ao lado da produção, e cada evento recebido vai para os dois. Você tem a experiência do ngrok, eventos ao vivo no seu notebook, sem o desgaste do túnel. Quando o notebook entra em repouso, só o destino do túnel falha. A produção continua rodando, os eventos continuam sendo registrados e as entregas com falha para o seu notebook ficam lá, esperando o replay quando você voltar.
Para homologação, você adiciona o ambiente de homologação como mais um destino e, no Pro e acima, um filtro por tipo de evento pode mandar para ele só uma parte do tráfego de produção. Para depuração, você filtra o log de eventos por status ou por app (uma URL de entrada para uma origem) e faz o replay do que estiver tentando reproduzir.
ngrok + AnyHook é o padrão que funciona
Se o que está pegando você é especificamente o túnel entregar uma URL nova a cada reinício, e você ficar colando essa URL de novo no painel do provedor, isso tem uma resposta curta própria: dê ao provedor uma URL que não muda.
A combinação que funciona na prática: ngrok nos primeiros 30 minutos de uma integração nova, porque é o jeito mais rápido de chegar ao "funciona na minha máquina", e AnyHook para tudo depois disso, ou seja, log persistente, envio para vários ambientes, replay, novas tentativas e alertas.
O AnyHook dá a você uma URL de entrada estável que não depende do notebook de ninguém, encaminha para vários destinos (produção, homologação, seu túnel, onde for) e mantém um log completo com replay. Você continua usando o ngrok no desenvolvimento local, porque nada o supera ali, e para de usar o ngrok para qualquer coisa que você ficaria triste em perder.
O custo do "é só usar o ngrok"
As equipes que mais perdem tempo com problemas de webhooks são quase sempre as que trataram o ngrok como estratégia de produção:
- A homologação quebra toda vez que alguém fecha o notebook
- Quedas em produção deixam lacunas permanentes nos dados
- "Qual era o payload daquele evento?" não tem resposta dois dias depois
- Quem acabou de entrar no time não consegue reproduzir bugs, porque não há histórico de eventos para fazer o replay
Pagar pelo ngrok não resolve nada disso. Um túnel mais rápido para o mesmo notebook continua sendo um túnel para um notebook.
Conclusão
O que você quer além do desenvolvimento local é uma camada de webhooks que more em outro lugar que não a máquina de um dev: persistente, com replay e capaz de enviar o mesmo evento para quantos destinos você quiser. É essa mudança que faz os webhooks deixarem de ser um incêndio semanal.
Se você ainda está decidindo se vai receber push, Webhooks vs polling defende a escolha pelo modo de falha, e não pela eficiência. E, quando você já estiver recebendo em serverless, Como receber webhooks na Vercel sem perder nenhum cobre as partes que quebram em produção, mas nunca localmente.