Test Webhooks and Callbacks from Localhost
Payment providers, SaaS platforms, and CI systems need a public HTTPS endpoint to deliver webhooks. Running your API on localhost blocks them unless you expose localhost with a tunnel. Asyx gives you a stable https://<name>.tunnel.asyx.ai URL you can register in Stripe, GitHub, Shopify, and similar dashboards.
Why webhooks need a tunnel
Webhooks are server-to-server HTTP POSTs. They cannot reach 127.0.0.1. A tunnel forwards:
Stripe → https://you.tunnel.asyx.ai/webhooks/stripe → localhost:4242
HTTPS is required by most providers. Asyx terminates TLS at the edge and forwards to your local listener.
Setup
1. Run your webhook handler locally
Example: API listening on port 4242 with route POST /webhooks/stripe.
2. Open the tunnel
asyx tunnel --http --port 4242
Note the public URL, e.g. https://acme.tunnel.asyx.ai.
3. Register the endpoint
In the provider dashboard, set:
https://acme.tunnel.asyx.ai/webhooks/stripe
Use the exact path your framework expects.
4. Trigger a test event
Use the provider’s “Send test webhook” button or CLI. Watch your local logs for the POST.
Stable URL advantage
Rotating random URLs break webhook configs. Asyx keeps the same hostname between sessions—only the tunnel must be running when events arrive. For long-running local dev, leave the tunnel open; for CI, script asyx tunnel in the job.
Common providers
| Provider | Typical local path | Notes |
|---|---|---|
| Stripe | /webhooks/stripe | Verify signing secret in handler |
| GitHub | /api/github/webhook | Set webhook secret header check |
| Shopify | /webhooks/shopify | HMAC validation required |
| Twilio | /sms/inbound | Configure inbound URL in console |
Security practices
- Validate signatures — Never trust raw POST bodies; use each provider’s HMAC or signing secret.
- Use test mode keys — Stripe/GitHub test events only during development.
- Stop the tunnel when not testing—reduces accidental exposure.
- Quickpass — If the webhook path shares a server with a browser UI, consider splitting ports or using access groups for human-facing routes.
Related guides
- Expose localhost
- Expose Web + API — SPA + API on one origin
- Publish in 60 Seconds
FAQ
Do webhooks work on the free tier?
Yes, while your tunnel is active and within fair-use limits.
Can I use a custom path prefix?
Yes. The tunnel forwards the full request path to your local server.
What if my laptop sleeps?
Missed webhooks are not retried to your laptop. Use a staging server for always-on endpoints.