Custom HTTP Responses

Configure a response

Use a custom response to exercise your test sender’s success and failure handling. You need management access to an active endpoint.

1. Open the Response tab or select Configure response.
2. Set HTTP status. Try 200 for acceptance, 400 for a client error or 500 for a simulated server failure.
3. In Response headers, enter one Name: Value per line, for example Content-Type: application/json.
4. Enter this Response body, then select Save response:

{"received":true,"environment":"test"}

Wait for successful saving. Changes affect subsequent requests across the whole endpoint, including all subpaths; this is not per-path mock routing.

Verify the saved response

In a Bash-compatible shell with cURL installed, set WEBHOOK_URL to the receiving URL copied from your endpoint. Replace <YOUR_RECEIVING_URL> including the angle brackets, without a trailing slash; keep the single quotes. Reuse that variable for the examples on this page.

Set the variable first as in Quickstart, then run:

curl --include --request POST "${WEBHOOK_URL}/response-test" \
  --header 'Content-Type: application/json' \
  --data '{"test":true}'

Compare cURL’s status, Content-Type and body with your saved values. For a saved 200 response, expect the JSON above; switch to 400 or 500 and send again to observe those statuses.

Capture and response status

A saved custom 4xx or 5xx response can accompany a successful capture. If a sender reports a timeout or service error, check history before resending: persistence may already have succeeded and a resend can create a duplicate.

Capture occurs before the configured response. A 500 simulation tests the sender’s reaction; it does not make WebhookKit run application logic or schedule retries.

Response limits

Allowed statuses are 200–599. Configure at most 50 headers with no more than 16,384 combined UTF-8 bytes in header names and values. Names must be valid HTTP header names; values cannot contain line breaks.

Transport headers are disallowed: Connection, Content-Length, Host, Keep-Alive, Proxy-Authenticate, Proxy-Authorization, TE, Trailer, Transfer-Encoding and Upgrade.

The UTF-8 response body uses the configured body byte limit. HEAD requests and HTTP 204/304 responses omit the wire body even if body content is saved.

Reset to default

Select Reset to default and wait for completion. Send another request: expect HTTP 200 and an empty body. Previously captured requests keep their historical configuration snapshot.