Saltar al contenido principal

Pruebas con ngrok

DVS necesita un endpoint HTTPS accesible desde Internet pública para entregar webhooks. Durante el desarrollo, ngrok crea un túnel público hacia el servidor local con un solo comando.

Configuración​

  1. Instalar ngrok: brew install ngrok (macOS) o descargar desde ngrok.com.
  2. Registrarse para una cuenta gratis y ejecutar ngrok config add-authtoken <your-token>.
  3. Iniciar el receptor de webhook local (por ejemplo, en el puerto 8080).
  4. Ejecutar ngrok http 8080.

ngrok imprime una URL pública como https://abc123.ngrok-free.app. Todo lo que se envíe ahí se reenvía a localhost:8080.

Informar a DVS​

Enviar un correo a support@osigu.com solicitando registrar la URL de ngrok como endpoint de webhook temporal de desarrollo. Incluir:

  • El slug del tenant
  • La URL completa de ngrok
  • Los event_types que se quieren recibir (o [] para todos)
  • Si se usa hmac_signature (sí — igual que en producción) o un tipo de auth distinto

El operador de OSIGU ejecuta el endpoint administrativo para registrarlo. Se obtendrá el mismo webhook secret que se usa en producción (o uno distinto para desarrollo — es decisión propia).

Probar la conectividad​

Pedir a OSIGU que dispare un evento test.ping:

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

Un evento sintético llega a la URL de ngrok. Si el receptor retorna 2xx y verifica el HMAC correctamente, todo está listo.

Tropiezos comunes​

El body se reformatea y la signature falla

Algunos proxies locales (incluido ngrok mismo, en raras ocasiones) podrían modificar el body. Si la verificación de signature falla con ngrok pero funciona en producción, registrar el body raw y el timestamp que ngrok entrega y compararlo con lo que se calcula. Generalmente esto es un problema de parsing del body del lado del cliente, no de ngrok.

La URL de ngrok cambia en cada reinicio

El plan gratuito de ngrok asigna un subdominio distinto en cada ejecución. O se paga por un subdominio estático (~$8/mes) o hay que estar preparado para pedirle a OSIGU que actualice la URL registrada en cada sesión.

Auto-deshabilitación tras fallas

Si el servidor de desarrollo está caído por un tiempo, DVS puede auto-deshabilitar el endpoint tras 10 fallas consecutivas. Contactar a OSIGU para reactivarlo.

Cuando todo esté listo para producción​

  1. Implementar el endpoint HTTPS real en el dominio propio.
  2. Enviar un correo a OSIGU con la URL de producción.
  3. OSIGU lo registra como un nuevo webhook_endpoint (o rota el existente).
  4. Confirmar con :test contra el nuevo endpoint.
  5. Pedir a OSIGU que retire el endpoint de ngrok.