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​

The Traffic Policy configuration reference for this action.

Supported Phases​

on_http_request, on_http_response

Type​

custom-response

Configuration Fields​

  • status_codeintegerRequired

    Status code of the custom response being sent back.

  • contentstring

    Body of the custom response being sent back.

    Supports CEL Interpolation.

  • headersobjectCEL

    Map 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 properties 10.

    Supports CEL Interpolation.

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.

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.