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_code
integer
default:200

Status code of the custom response being sent back.

​
body
string
Supports CEL

Body of the custom response being sent back.

​
headers
object
Supports CEL

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.

​
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. Keep in mind that because this action bypasses the upstream server, request bodies will not be forwarded and will not be visible within the ngrok Traffic Inspector.

​
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
          body: <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 503
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 Response for Internal Endpoint Downtime

The following Traffic Policy configuration demonstrates how to use the custom-response action to redirect to a URL if an internal endpoint is returning an error.

​
Example Traffic Policy Document

on_http_request:
  - actions:
      - type: forward-internal
        config:
          url: https://endpoint-1.internal
          on_error: continue
      - type: custom-response
        config:
          status_code: 302
          headers:
            location: https://www.example.com

​
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:
          body: '{"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 the default 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
          body: 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.