Reference

Field-by-field reference for wsignal.config.ts.

Full Example

import { defineConfig } from "@wsignal/cli"

export default defineConfig({
  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 },
        headers: {
          "x-powered-by": "wsignal",
        },
      },
      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",
        },
      },
    },
  ],
})

Root Fields

port

• Type: number
• Default: 8787

The TCP port used by the local HTTP server.

storage

• Type: object
• Default: omitted

Storage-level options for JSONL persistence.

endpoints

• Type: EndpointConfig[]
• Required: yes

List of webhook endpoints to register on the local server.

storage

storage.dir

• Type: string
• Default: .wsignal

Directory where log files are stored. Relative paths resolve from the current working directory.

storage.file

• Type: string
• Default: events.jsonl

Central log file used by endpoints that do not specify their own logFile.

storage.rotate

• Type: object

Controls size-based log rotation.

storage.rotate.maxSizeMb

• Type: number
• Default: 10

Rotate the active log file when its size reaches the configured megabyte limit.

storage.rotate.maxFiles

• Type: number
• Default: 20

Maximum number of rotated files to retain per base log file.

EndpointConfig

name

• Type: string
• Required: yes

Human-readable endpoint name used in summaries, saved events, and filtering commands.

path

• Type: string
• Required: yes

Request path to match, including the leading slash.

method

• Type: string | string[]
• Default: POST

Allowed HTTP method or methods for the endpoint.

logFile

• Type: string
• Default: inherit storage.file

Custom log file for one endpoint. Relative paths resolve inside storage.dir.

response

• Type: EndpointResponseConfig

Static response returned to the incoming webhook request after the event has been persisted.

forward

• Type: EndpointForwardConfig | EndpointForwardConfig[]

Optional follow-up request target or list of targets issued after local persistence and response.

proxy

• Type: EndpointProxyConfig

Optional synchronous upstream request. When present, wsignal returns the upstream response to the original caller instead of the static response.

EndpointResponseConfig

status

• Type: number
• Default: 200

headers

• Type: Record<string, string>
• Default: {}

json

• Type: unknown

Serialized to JSON. Cannot be combined with text.

text

• Type: string

Plain-text response body. Cannot be combined with json.

EndpointForwardConfig

name

• Type: string

Optional target name used in forward result output. Names must be unique within one endpoint when provided.

url

• Type: string
• Required: yes

Destination URL for the forwarded request.

method

• Type: string
• Default: original request method

Override method for the forwarded request.

headers

• Type: Record<string, string>
• Default: {}

Headers merged into the forwarded request. If a key already exists on the original request, the forward config wins.

when

• Type: EndpointForwardMatchConfig

Optional match rules for this target. If omitted, the target receives every event for the endpoint.

EndpointForwardMatchConfig

headers

• Type: Record<string, string | string[]>

Header conditions for a forward target. Header names are matched case-insensitively. A string array matches when the incoming value equals any configured value.

query

• Type: Record<string, string | string[]>

Query string conditions for a forward target. Query parameter names are case-sensitive. A string array matches when the incoming value equals any configured value.

EndpointProxyConfig

url

• Type: string
• Required: yes

Destination URL for the proxied request. The original query string is appended to this URL.

method

• Type: string
• Default: original request method

Override method for the proxied request.

headers

• Type: Record<string, string>
• Default: {}

Headers merged into the proxied request. If a key already exists on the original request, the proxy config wins.