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.