Skip to main content

Documentation Index

Fetch the complete documentation index at: https://wsignal.mintlify.app/llms.txt

Use this file to discover all available pages before exploring further.

​
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