Mock API Dynamic Responses

How It Works

A source can define config.custom_response.body as the fallback response and config.custom_response.rules as ordered dynamic response rules. FastHook evaluates rules before the fallback body. The first enabled matching rule wins.

Rules are evaluated after the source exists, is enabled, the HTTP method is allowed, and source authentication passes. This keeps mock behavior behind the same ingress controls as production webhook capture.

• Match by method, path, query, headers, and body fields.
• Return JSON, text, or XML.
• Set status codes such as 200, 201, 202, 400, 404, or 409.
• Attach safe custom response headers.
• Use templates such as {{body.id}}, {{headers.x-request-id}}, {{query.mode}}, {{path}}, and {{request.id}}.
• Keep request, event, and attempt evidence for debugging.

Client or provider
  -> FastHook source URL
  -> source auth and allowed method checks
  -> request captured
  -> first matching dynamic response rule
  -> response returned immediately
  -> optional events routed to destinations

Configure A Mock API Source

Open a source in the dashboard, enable Customize response, set a fallback body, then paste a JSON rules array into Dynamic response rules. The fallback body is returned when no rule matches.

For API automation, PATCH the source config. Keep allowed_http_methods aligned with the routes you want to mock.

{
  "config": {
    "allowed_http_methods": ["GET", "POST"],
    "custom_response": {
      "content_type": "json",
      "body": "{\"ok\":true,\"fallback\":true}",
      "rules": [
        {
          "name": "create order",
          "match": {
            "method": "POST",
            "path": "/orders",
            "query": { "mode": "mock" },
            "body": {
              "type": "order.created",
              "data.id": { "$exists": true }
            }
          },
          "response": {
            "status": 201,
            "content_type": "json",
            "headers": {
              "x-mock-rule": "create-order"
            },
            "body": "{\"ok\":true,\"order_id\":\"{{body.data.id}}\",\"request_id\":\"{{request.id}}\"}"
          }
        }
      ]
    }
  }
}

Rule Match Fields

Each rule can match one or more request fields. Omitted match fields are ignored. Header names are compared case-insensitively, and JSON body paths can use dot notation for nested fields.

• method: string or array of methods such as POST or [GET, POST].
• path: exact string or operator object matched against the request path.
• query: object matched against query parameters.
• headers: object matched against lowercase header names.
• body: object, scalar, or operator object matched against parsed JSON body when possible.
• enabled: false disables a rule without deleting it.

{
  "match": {
    "method": ["GET", "POST"],
    "path": { "$starts_with": "/v1/orders" },
    "headers": {
      "x-env": "staging"
    },
    "query": {
      "version": { "$in": ["2026-01", "2026-06"] }
    },
    "body": {
      "customer.email": { "$contains": "@example.com" }
    }
  }
}

Operators

Operators make rules useful for realistic mock behavior without writing code. Use exact matches for stable contracts and operators for families of test cases.

• $eq: actual value must equal the expected value.
• $ne: actual value must not equal the expected value.
• $contains: string or array contains the expected value.
• $starts_with: string starts with the expected value.
• $ends_with: string ends with the expected value.
• $exists: field exists when true, or is absent/null when false.
• $in: actual value is one of the listed values.
• $regex: actual string matches the regular expression.

Response Templates

Templates let a mock response echo useful request values without running a transformation. Unknown values render as an empty string. For complex reshaping, route the request through a connection transformation and deliver it to a destination.

• {{request.id}} or {{request_id}} for the FastHook request id.
• {{source.id}} and {{team.id}} for source and team ids.
• {{method}}, {{path}}, {{query}}, and {{now}} for request metadata.
• {{headers.x-request-id}} for a request header.
• {{query.mode}} for a query parameter.
• {{body.data.id}} for a JSON body field.
• {{body}} or {{raw_body}} for the original request body.

{
  "response": {
    "status": 409,
    "content_type": "json",
    "body": "{\"ok\":false,\"error\":\"duplicate_order\",\"id\":\"{{body.data.id}}\"}"
  }
}

Mock API Vs Mock Destination

A dynamic source response is for the caller that sends the inbound request. A mock destination is for testing FastHook outbound delivery after routing. They solve opposite sides of the pipeline.

• Use dynamic source responses when a client, provider, or test suite needs FastHook to reply with realistic API responses.
• Use a mock destination when you want to test routing, transformations, retries, and attempts without calling a real receiver.
• Use both when you need a source URL that replies like an API and also records routed branch evidence.

Testing With Curl

Use curl -i so the status code, headers, and response body are visible. Then open Requests or the request trace page to confirm that FastHook captured the request.

curl -i -X POST "https://hook-xxxxxx.fasthook.io/orders?mode=mock" \
  -H "content-type: application/json" \
  -H "x-env: staging" \
  -d '{
    "type": "order.created",
    "data": {
      "id": "ord_123"
    }
  }'

Operational Guidance

• Keep response bodies small and deterministic.
• Put the most specific rules first.
• Use a fallback body for unknown routes.
• Keep secrets out of response templates and headers.
• Use source authentication for any public mock endpoint that should not be open.
• Use connection filters and transformations for downstream delivery behavior; keep source responses focused on the caller acknowledgement.
• Inspect Requests for inbound behavior and Events or Attempts for downstream behavior.

Next

• Mock API
• Custom source responses
• Receive webhooks
• Request trace page
• Webhook debug online