Pular para o conteúdo principal

Testando com ngrok

O DVS precisa de um endpoint HTTPS acessível pela Internet pública para entregar webhooks. Durante o desenvolvimento, o ngrok cria um túnel público para o servidor local com um único comando.

Setup​

  1. Instale o ngrok: brew install ngrok (macOS) ou faça download em ngrok.com.
  2. Faça cadastro para uma conta gratuita e execute ngrok config add-authtoken <seu-token>.
  3. Inicie o webhook receiver local (por exemplo, na porta 8080).
  4. Execute ngrok http 8080.

O ngrok imprime uma URL pública como https://abc123.ngrok-free.app. Qualquer POST feito para essa URL é encaminhado para localhost:8080.

Informe o DVS​

Envie um e-mail para support@osigu.com solicitando o registro da URL do ngrok como webhook endpoint temporário de dev. Inclua:

  • O slug do tenant
  • A URL completa do ngrok
  • event_types desejados (ou [] para todos)
  • Se deseja usar hmac_signature (sim — igual à prod) ou outro tipo de auth

O operador da OSIGU executa o endpoint admin para registrar. Será fornecido o mesmo webhook secret usado em produção (ou outro para dev — sua escolha).

Testar a conectividade​

Solicite à OSIGU o disparo de um evento test.ping:

# A OSIGU executa internamente:
POST /v1/webhook-endpoints/{your_endpoint_id}:test

Um evento sintético chega à URL do ngrok. Se o receiver retornar 2xx e verificar a HMAC corretamente, tudo está funcionando.

Pegadinhas comuns​

O body é reformatado e a signature falha

Alguns proxies locais (incluindo o próprio ngrok, raramente) podem modificar o body. Se a verificação de signature falhar no ngrok mas funcionar em produção, registre o raw body e o timestamp entregues pelo ngrok e compare com o valor calculado. Geralmente trata-se de um problema de parsing do body do seu lado, não do ngrok.

A URL do ngrok muda a cada restart

O ngrok gratuito gera um subdomínio diferente a cada execução. As opções são pagar por um subdomínio estático (~US$ 8/mês) ou solicitar à OSIGU a atualização da URL registrada em cada sessão.

Auto-desabilitação após falhas

Se o servidor de dev ficar fora do ar por um período, o DVS pode desabilitar automaticamente o endpoint após 10 falhas consecutivas. Entre em contato com a OSIGU para reativar.

Quando estiver pronto para produção​

  1. Implemente o endpoint HTTPS real no seu domínio.
  2. Envie e-mail à OSIGU com a URL de produção.
  3. A OSIGU registra como novo webhook_endpoint (ou faz a rotação do existente).
  4. Confirme com :test no novo endpoint.
  5. Solicite à OSIGU a remoção do endpoint do ngrok.