Features on spectralab

Echo Mode

Mon, 01 Jan 0001 00:00:00 +0000

Echo Mode#

echo: true makes Simuhook return the request body verbatim as the response.

id: debug-echo
method: POST
path: /webhooks/echo
response:
 status_code: 200
 echo: true

curl -X POST http://localhost:8080/webhooks/echo \
 -H "Content-Type: application/json" \
 -d '{"hello":"world"}'
# → {"hello":"world"}

Why It’s Useful#

Echo mode is a debugging tool — it shows you exactly what your client is sending, byte for byte. Combined with the TUI dashboard you can see the request headers, query, body, and the echoed response all in one place.

Response Variants

Mon, 01 Jan 0001 00:00:00 +0000

Response Variants#

A stub can define several possible responses with a responses[] list instead of a single response. This lets you simulate flaky or varied third-party behavior: mostly success, sometimes an error, occasionally a timeout.

id: flaky-webhook
method: POST
path: /webhooks/payment
responses:
 - status_code: 200
 body: '{"status":"completed","transaction_id":"txn_12345"}'
 weight: 80
 - status_code: 400
 body: '{"error":"insufficient_funds"}'
 weight: 15
 - status_code: 500
 body: '{"error":"internal_error"}'
 weight: 5
 delay: 2s

Send the same request several times and you’ll see roughly: 80% succeed, 15% get a 400, 5% get a slow 500.

Delays

Mon, 01 Jan 0001 00:00:00 +0000

Delays#

delay adds artificial latency before the response is sent — useful for testing client timeouts, retries, and back-off behavior.

id: slow-endpoint
path: /slow
response:
 status_code: 200
 body: '{"ok":true}'
 delay: 2s

time curl -s http://localhost:8080/slow
# → {"ok":true}
# real 0m2.003s

Duration Syntax#

delay accepts Go duration syntax:

YAML	Duration
`delay: 0s` (or omit)	Instant — normal operation
`delay: 200ms`	200 milliseconds
`delay: 500ms`	Moderate latency
`delay: 2s`	Client timeout testing
`delay: 5s`	Aggressive timeout testing
`delay: 2m30s`	Two and a half minutes

Where Delays Apply#

The singular response — response.delay.
Any variant inside responses[] — per-variant latency (each variant can have a different delay).

id: flaky-webhook
method: POST
path: /webhooks/payment
responses:
 - status_code: 200
 body: '{"status":"completed"}'
 weight: 80
 - status_code: 500
 body: '{"error":"internal_error"}'
 weight: 5
 delay: 2s  # only this variant is slow

Notes#

Delays are applied after the request is matched and template data is built, and the measured latency in the logs and dashboard includes the delay.
The dashboard’s latency stats (avg/min/max/p95) count the artificial delay, so a delay: 2s stub will show up in p95 — expected, since that’s the latency your client experiences too.

Also See#

stubs/user-create.yaml — 200ms delay.
stubs/order-placed.yaml — 500ms delay.
stubs/flaky-webhook.yaml — 2s delay on one variant.

Logging

Mon, 01 Jan 0001 00:00:00 +0000

Logging#

Every request to a webhook endpoint is logged as a JSON line:

Log file	Contents
`logs/<webhook-id>.log`	Matched requests for the endpoint with that `id`.
`logs/_unmatched.log`	Requests that matched no endpoint (responded `404`).

The log directory defaults to logs/ — override with --log-dir or the LOG_DIR environment variable.

Log Entry#

{
 "timestamp": "2026-08-18T10:30:00.123Z",
 "request_id": "uuid-v4",
 "webhook": "health",
 "method": "GET",
 "path": "/health",
 "headers": {"User-Agent": "curl/8.7.1"},
 "body": "",
 "query": {},
 "response_status": 200,
 "response_headers": {"Content-Type": "application/json"},
 "response_body": "",
 "latency_ms": 0.02,
 "matched": true
}

Field	Description
`timestamp`	Request time, RFC3339 with milliseconds (UTC).
`request_id`	Unique request ID (same value available in templates as `{{.RequestID}}`).
`webhook`	The endpoint `id` that matched (absent / empty for unmatched).
`method`	HTTP method.
`path`	Request path.
`headers`	Request headers (map).
`body`	Request body.
`query`	Query parameters (map).
`response_status`	Status code returned.
`response_headers`	Response headers (map).
`response_body`	Response body.
`latency_ms`	Total time to serve the request — includes any configured delay.
`matched`	`true` if a stub matched, `false` for a `404`.

Capping Stored Bodies#

Large payloads blow up your logs. --max-log-body N (or LOG_MAX_BODY) caps the stored body / response_body at capture time, in bytes: