Use ngrok with wsignal

Expose your local wsignal server through ngrok so third-party webhook providers can reach it.

Overview

wsignal listens on your local machine. ngrok gives that local server a public URL so external webhook providers can deliver requests to it.

The setup is:

1. Start wsignal on its local port.
2. Start ngrok and forward traffic to that same port.
3. Configure your provider to send webhooks to the ngrok URL plus the matching wsignal endpoint path.

Default Starter Flow

If you used the starter config from wsignal init --yes, wsignal listens on:

• Port: 8787
• Endpoint path: /webhook

Start wsignal:

wsignal dev

In a second terminal, start ngrok:

ngrok http 8787

ngrok will print a public forwarding URL such as:

https://example.ngrok.app

Your full webhook URL becomes:

https://example.ngrok.app/webhook

Send your provider’s webhook traffic to that URL.

Multiple Endpoints

ngrok only forwards to the local wsignal port. wsignal still handles routing by path.

For example, if your config contains:

export default {
  port: 8787,
  endpoints: [
    { name: "github", path: "/github", method: "POST" },
    { name: "stripe", path: "/stripe", method: "POST" },
    { name: "alerts", path: "/alerts", method: "POST" },
  ],
}

And you run:

ngrok http 8787

Then the provider URLs are:

• https://example.ngrok.app/github
• https://example.ngrok.app/stripe
• https://example.ngrok.app/alerts

Verifying Traffic

After you configure the remote webhook URL:

1. Trigger a test event from the provider.
2. Check the running wsignal dev terminal.
3. Review stored records locally:

wsignal logs
wsignal inspect --endpoint default

If you are using named endpoints like github or stripe, inspect those instead:

wsignal inspect --endpoint github

Common Issues

404 No webhook endpoint matched this request.

The provider is calling the wrong path.

Example:

• Config path: /webhook
• Wrong public URL: https://example.ngrok.app/
• Correct public URL: https://example.ngrok.app/webhook

405 Method not allowed.

The provider is using a different HTTP method than the one configured for the endpoint.

If the endpoint only allows POST, a GET validation request will fail unless you add that method to the endpoint config.

No requests are reaching wsignal

Check:

• wsignal dev is running
• ngrok is forwarding to the correct port
• Your provider is using the current ngrok URL
• The provider URL includes the correct endpoint path

Example End-to-End Test

Start wsignal:

wsignal dev

Start ngrok:

ngrok http 8787

Use the public URL with curl:

curl -X POST https://example.ngrok.app/webhook \
  -H "content-type: application/json" \
  -d '{"ok":true}'

Then confirm the event was saved:

wsignal inspect --endpoint default

Related Docs

• Quickstart
• Configuration Overview
• logs
• inspect