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

# Behavior

> Request matching, response semantics, forwarding, and log rotation.

## Request Matching

`wsignal` matches requests by pathname first and then by allowed method.

### Unmatched Path

If no endpoint matches the request path:

* Status: `404`
* Body: `No webhook endpoint matched this request.`

### Method Mismatch

If the path exists but the method is not allowed:

* Status: `405`
* `Allow` header is set to the configured methods
* Body: `Method not allowed.`

## Persistence Before Response

For static response and forwarding endpoints, `wsignal` writes the event to disk before it acknowledges the request.

That means:

* A successful response implies the event was persisted successfully.
* A write failure produces a `500` response with `Failed to persist webhook event.`

## Forwarding

Endpoint forwarding is asynchronous and happens after:

1. Local persistence succeeds
2. The local response is sent

Forwarding uses:

* The configured `forward.method`, or the original request method when omitted
* The original request body when the method allows a body
* The original headers, except `host` and `content-length`
* Any `forward.headers`, which override existing header keys

An endpoint can define one forward target or multiple targets. Each target is evaluated independently after the local response. Targets with no `when` rules receive every event. Targets with `when.headers` or `when.query` only receive events where every configured condition matches.

## Proxying

Endpoint proxying is synchronous. It is intended for flows where the caller needs the upstream response, such as local login testing.

Proxying uses:

* The configured `proxy.method`, or the original request method when omitted
* The original request body when the method allows a body
* The original headers, except `host` and `content-length`
* Any `proxy.headers`, which override existing header keys
* The original query string, appended to `proxy.url`

`wsignal` returns the upstream status, headers, and body to the original caller. Redirect responses are not automatically followed, so upstream `Location` and `Set-Cookie` headers can be returned.

If the upstream request fails, `wsignal` returns `502` with `Proxy request failed.`

## Log Rotation

Rotation is size-based.

Before appending a new event, `wsignal` checks the current target log file size. When the file is at or above the configured size threshold, it:

1. Renames the active file to a timestamped rotated file
2. Creates a new active file on the next append
3. Prunes the oldest rotated files if they exceed `maxFiles`

Rotated files remain readable by `logs`, `inspect`, and `replay`.

## Record Loading

When a config file is present, `wsignal` discovers:

* The central log file
* Each endpoint-specific log file
* Rotated variants of each base log file

When no config file is present, `logs`, `inspect`, and `replay` fall back to `.wsignal` in the current working directory.