Skip to main content

Testing with ngrok

DVS needs an HTTPS endpoint reachable from the public Internet to deliver webhooks. During development, ngrok creates a public tunnel to your local server in one command.

Setup​

  1. Install ngrok: brew install ngrok (macOS) or download from ngrok.com.
  2. Sign up for a free account, run ngrok config add-authtoken <your-token>.
  3. Start your local webhook receiver (e.g., on port 8080).
  4. Run ngrok http 8080.

ngrok prints a public URL like https://abc123.ngrok-free.app. Anything posted there is forwarded to localhost:8080.

Tell DVS about it​

Email support@osigu.com asking to register your ngrok URL as a temporary dev webhook endpoint. Include:

  • Your tenant slug
  • The full ngrok URL
  • event_types you want to receive (or [] for all)
  • Whether to use hmac_signature (yes — same as prod) or a different auth type

OSIGU's operator runs the admin endpoint to register it. You'll get the same webhook secret that prod uses (or a different one for dev — your call).

Test connectivity​

Ask OSIGU to fire a test.ping event:

# OSIGU runs internally:
POST /v1/webhook-endpoints/{your_endpoint_id}:test

A synthetic event arrives at your ngrok URL. If your receiver returns 2xx and verifies the HMAC correctly, you're good to go.

Common gotchas​

Body is reformatted, signature fails

Some local proxies (including ngrok itself, rarely) might modify the body. If signature verification fails on ngrok but works in prod, log the raw body and timestamp ngrok delivers and compare against what you'd compute. Mostly this is a body-parsing problem on your side, not ngrok.

ngrok URL changes every restart

Free ngrok gives a different subdomain each run. Either pay for a static subdomain (~$8/mo) or be prepared to ask OSIGU to update your registered URL each session.

Auto-disable after failures

If your dev server is down for a while, DVS may auto-disable your endpoint after 10 consecutive failures. Contact OSIGU to reactivate.

When you're ready for prod​

  1. Implement your real HTTPS endpoint on your domain.
  2. Email OSIGU with the production URL.
  3. OSIGU registers it as a new webhook_endpoint (or rotates your existing one).
  4. Confirm with :test against the new endpoint.
  5. Ask OSIGU to retire the ngrok endpoint.