Custom Responses

By default, HookSense returns 200 OK with {"ok": true} for every captured webhook. That's fine for inspection, but real providers expect specific responses — and sometimes you want to deliberately fail to test retry behavior. Custom responses let you control exactly what your endpoint returns.

Configuration

1. Open your endpoint page
2. Click the Settings (gear) icon in the toolbar
3. Configure these fields and save:

• Status code — Any valid HTTP status (100–599). Common: 200, 201, 204, 400, 401, 404, 422, 500, 503
• Response body — Raw string. JSON, plain text, or HTML are all valid. Up to 10 KB.
• Response headers — Key-value pairs. Content-Type defaults to application/json; override it for text/HTML responses.

Settings apply to every incoming request on that endpoint. Toggle Use default response in the same panel to revert without losing your config.

Use Cases

Match What the Provider Expects

Some providers retry until they receive an exact response. Examples:

• Stripe — accepts any 2xx; the body is ignored. Default is fine.
• Twilio — expects 200 with TwiML XML. Set Content-Type: application/xml and a body like <Response/>.
• Slack slash commands — must respond within 3 seconds with JSON containing response_type.

Simulate Failure to Test Retries

Set the response to 500 Internal Server Error to verify your provider's retry logic. Combine with the Health dashboard to watch fail rate climb in real time.

Validate Provider Behavior on Specific Status

Test how a provider handles 410 Gone (most stop retrying), 422 Unprocessable Entity (some give up, some retry), or 429 Too Many Requests (most respect Retry-After).

Return Mock Data

Use HookSense as a stub server during integration testing. Return canned JSON for your test suite, no backend needed:

Status: 200
Content-Type: application/json
Body:
{
  "id": "stub_1",
  "status": "ok",
  "items": []
}

Blocked Headers

For security, these response headers are silently dropped if you try to set them:

• Set-Cookie — prevents cross-origin cookie injection
• Location — prevents open-redirect abuse
• Content-Security-Policy, Strict-Transport-Security, X-Frame-Options — host-level security headers
• Transfer-Encoding, Connection, Host — hop-by-hop / infrastructure headers
• CORS headers (Access-Control-*) — managed by HookSense

Custom responses require Hook plan or above.