wsignal

Fast lightweight local webhook receiver CLI built with TypeScript.

wsignal is designed around one job: receive webhooks locally and always log them. It supports multiple endpoints from a typed config file, JSONL log storage with rotation, replay, and an interactive log browser.

Read the docs at wsignal.mintlify.app.

Install

npm install -g @wsignal/cli

Or with pnpm:

pnpm add -g @wsignal/cli

If you prefer to pin the CLI per project:

npm install -D @wsignal/cli

Or run it directly in this repo during development:

pnpm build
node dist/cli.js --help

Quick Start

Create a starter config:

wsignal init --yes

This writes wsignal.config.ts:

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

Start the receiver:

wsignal dev

Send a test request:

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

Browse saved records:

wsignal logs
wsignal inspect --endpoint default

Config

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

Example:

export default {
  port: 8787,
  storage: {
    dir: ".wsignal",
    file: "events.jsonl",
    rotate: {
      maxSizeMb: 10,
      maxFiles: 20,
    },
  },
  endpoints: [
    {
      name: "stripe",
      path: "/stripe",
      method: "POST",
    },
    {
      name: "github",
      path: "/github",
      method: "POST",
      logFile: "github.jsonl",
      response: {
        status: 200,
        json: { ok: true },
      },
      forward: [
        {
          name: "push",
          url: "http://localhost:3000/api/github-webhook",
          headers: {
            "x-forwarded-by": "wsignal",
          },
          when: {
            headers: {
              "x-github-event": "push",
            },
          },
        },
        {
          name: "audit",
          url: "http://localhost:4000/audit",
          when: {
            query: {
              mode: "test",
            },
          },
        },
      ],
    },
    {
      name: "login",
      path: "/login",
      method: "POST",
      proxy: {
        url: "http://localhost:3000/login",
        headers: {
          "x-proxied-by": "wsignal",
        },
      },
    },
  ],
}

Notes:

• Central JSONL logging is the default.
• Each endpoint can override logFile.
• Log rotation applies to both central and per-endpoint files.
• A webhook is only acknowledged after its log write succeeds.
• forward sends asynchronous follow-up request(s) after the local response.
• A forward target can use when.headers and when.query to receive only matching events.
• proxy sends the request upstream and returns the upstream response to the caller.

Commands

wsignal init [--yes] [--force]
wsignal dev [--config ./wsignal.config.ts]
wsignal logs [--interactive] [--endpoint github] [--last 20]
wsignal inspect --id evt_20260329_xxxxxx
wsignal replay evt_20260329_xxxxxx --to http://localhost:3000/test
wsignal update [--manager npm|pnpm] [--global|--dev] [--yes]

Logs

Stored records are written as JSONL in .wsignal/ by default.

Typical files:

.wsignal/events.jsonl
.wsignal/events.2026-03-29T12-00-00-000Z.jsonl
.wsignal/github.jsonl

Interactive browsing is available in TTY mode:

wsignal logs --interactive

Behavior

• Multiple endpoints share one local server port.
• Unmatched requests return 404.
• Method mismatches return 405.
• Forwarding happens after local persistence and response.
• replay preserves the recorded method, headers, and raw body.

Development

pnpm install
pnpm lint
pnpm format
pnpm typecheck
pnpm test
pnpm build

Documentation

Mintlify docs live in the docs/docs.json config and the docs/ directory.

pnpm docs:dev
pnpm docs:validate
pnpm docs:broken-links