Quickstart

Create a config, start the receiver, send a request, and inspect the result.

1. Create A Starter Config

wsignal init --yes

This writes wsignal.config.ts with one default endpoint:

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

2. Start The Receiver

wsignal dev

wsignal resolves wsignal.config.ts from the current working directory by default.

3. Send A Test Request

curl -X POST http://localhost:8787/webhook \
  -H "content-type: application/json" \
  -d '{"ok":true}'

For the starter config, the request will:

• Match the default endpoint
• Be written to .wsignal/events.jsonl
• Receive the default 200 response

4. Browse Saved Records

Show saved records:

wsignal logs

Inspect the most recent saved event for one endpoint:

wsignal inspect --endpoint default

5. Replay A Captured Event

Once you have an event ID, replay it to another URL:

wsignal replay evt_20260329_xxxxxx --to http://localhost:3000/test

Interactive Fallback

If you run wsignal dev without any config file present, wsignal starts an interactive setup flow instead of failing immediately.

Expose It Publicly With ngrok

To receive webhooks from third-party services on your local machine, run ngrok against the same port as wsignal:

ngrok http 8787

Then use the generated public URL plus your configured endpoint path, for example:

https://example.ngrok.app/webhook

Full guide: Use ngrok with wsignal

For the full config model, continue to the Configuration Overview.