Skip to main content

Custom Response

Overview​

The Custom Response Traffic Policy action enables you to return a hard-coded response back to the client that made a request to your endpoint.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Action Type​

custom-response

Configuration Fields​

ParameterTypeDescription
status_codeintRequired. Status code of the custom response being sent back.
contentstringBody of the custom response being sent back. Supports CEL Interpolation.
headersmap[string]stringMap of key-value headers of the custom response to be sent back. If content-type is not included in headers, this action will attempt to infer the correct content-type. Maximum 10.

Supported Phases​

  • on_http_request
  • on_http_response

Supported Schemes​

  • https
  • http

Behavior​

If this action is executed, no subsequent actions in your traffic policy will be executed.

on_http_request Usage​

When used during the on_http_request phase, this action bypasses the upstream server and immediately returns the configured response to the caller.

on_http_response Usage​

When used during the on_http_response, this action overwrites the response from the upstream server with the configured response.

Inferring Content-Type​

If the content-type header is not explicitly specified in headers, this action will attempt to infer the correct content-type based on the provided content.

CEL Interpolation​

You can access Traffic Policy variables and embed CEL expressions in this actions configuration values using CEL interpolation in the form of ${expression}. Check out the examples to see this in action.

For a complete list of variables and how to write expressions, see Expressions and Variables documentation.

Examples​

Custom HTML Maintenance Page​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a custom HTML maintenance page back for all requests to your endpoint.

Example Traffic Policy Document​

---
on_http_request:
  - actions:
      - type: "custom-response"
        config:
          status_code: 503
          content: "<html><body><h1>Service Unavailable</h1><p>Our servers are currently
            down for maintenance. Please check back later.</p></body></html>"
          headers:
            content-type: "text/html"

Example Request​

$ curl -i https://example.ngrok.app/dashboard
HTTP/2 200 OK
content-type: text/html

<html>
  <body>
    <h1>Service Unavailable</h1>
    <p>Our servers are currently down for maintenance. Please check back later.</p>
  </body>
</html>

In this example, when a request is made to any page on your endpoint, ngrok returns back the custom HTML maintenance page.

This setup is useful for when you want to temporarily disable your endpoint.

Custom JSON API Response with CEL Interpolation​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a JSON response with CEL Interpolation for the connection start time.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path == '/api/example'"
    actions:
      - type: "custom-response"
        config:
          status_code: 200
          content: "{\"connection-start\":\"${conn.ts.start}\"}"
          headers:
            content-type: "application/json"

Example Request​

$ curl https://example.ngrok.app/api/example
HTTP/2 200 OK
content-type: application/json

{
  "connection-start": "2024-06-24T15:30:00Z"
}

In this example, when a request is made to /api/example, ngrok returns a custom JSON response with a status code of 200. The response includes a content-type: application/json header and a JSON body that uses CEL Interpolation to show the connection start time using the conn.ts.start variable.

Custom Plaintext Response with Multiple CEL Interpolations​

The following Traffic Policy configuration demonstrates how to use the custom-response action to return a text/plain response with multiple CEL interpolations.

Example Traffic Policy Document​

---
on_http_request:
  - expressions:
      - "req.url.path == '/api/example'"
    actions:
      - type: "custom-response"
        config:
          status_code: 418
          content: "connection began at ${conn.ts.start}, now ${timestamp(time.now)}"
          headers:
            content-type: "text/plain"

Example Request​

$ curl https://example.ngrok.app/api/example
HTTP/2 418 I'm a teapot
content-type: text/plain

connection began at 2024-06-24T15:30:00Z, now 2024-06-24T16:30:00Z

In this example, when a request is made to /api/example, ngrok returns a custom plain text response with a status code of 418. The response includes a content-type: text/plain header and a body that uses multiple string interpolations to show the connection start time and the current time.

Action Result Variables​

The following variables are made available for use in subsequent expressions and CEL interpolations after the action has run. Variable values will only apply to the last action execution, results are not concatenated.

This action does not set any variables after it has been executed.