> ## Documentation Index
> Fetch the complete documentation index at: https://wsignal.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`:

```bash theme={null}
wsignal dev
```

In a second terminal, start `ngrok`:

```bash theme={null}
ngrok http 8787
```

`ngrok` will print a public forwarding URL such as:

```text theme={null}
https://example.ngrok.app
```

Your full webhook URL becomes:

```text theme={null}
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:

```ts theme={null}
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:

```bash theme={null}
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:

```bash theme={null}
wsignal logs
wsignal inspect --endpoint default
```

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

```bash theme={null}
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`:

```bash theme={null}
wsignal dev
```

Start `ngrok`:

```bash theme={null}
ngrok http 8787
```

Use the public URL with `curl`:

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

Then confirm the event was saved:

```bash theme={null}
wsignal inspect --endpoint default
```

## Related Docs

* [Quickstart](/getting-started/quickstart)
* [Configuration Overview](/configuration/overview)
* [logs](/commands/logs)
* [inspect](/commands/inspect)