> ## 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.

# Reference

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

## Full Example

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