The Add Headers action enables you to add custom headers to an HTTP request or response before delivery to the upstream service or client. This is useful for attaching metadata like request identifiers, applying security controls, or adjusting how applications process traffic.

​
Configuration Reference

The Traffic Policy configuration reference for this action.

​
Supported Phases

on_http_request, on_http_response

​
Type

add-headers

​
Configuration Fields

​
headers
object
Supports CEL
Map of header key to header value to be added.Minimum 1, Maximum 10.

​
Behavior

When configured in the on_http_request phase, this action will add the specified headers to incoming http requests before reaching the upstream server. When configured in the on_http_response phase, the specified headers are added to the http response from the upstream server.

​
Addition Only

This action will only add headers to the request or response. If the header already exists it will append another header with the same key unless it is the host header, see Special Cases. To replace or remove headers use the remove-headers action then add the header with the desired value.

​
Case Sensitivity

Header keys added through this action are normalized to lowercase per the HTTP/2 specification.

​
Ordering

Since actions are run in the order they are specified, to modify headers that have been added by other actions you must place this action after them in your traffic policy document.

​
Special Cases

  • Adding the host header override the existing value instead of appending another header.
  • You may not add or remove the user-agent header.
  • You may not use this action to add the ngrok-skip-browser-warning header to skip the ngrok browser warning on free accounts. For more information, check out the free plan limits guide.

​
Examples

​
Adding Client IP Headers to all HTTP requests

The following Traffic Policy configuration will add the client IP address to all HTTP requests.

​
Example Traffic Policy Document

on_http_request:
  - actions:
    - type: "add-headers"
      config:
        headers:
          x-client-ip: "${conn.client_ip}"
For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org and we are adding the following header to all requests:
  • x-client-ip with the value ${conn.client_ip} to demonstrate the use of CEL interpolation to include the client IP address.

​
Example Request

$ curl -i https://httpbin.ngrok.app/get

HTTP/2 200 OK
content-type: application/json

{
  "headers": {
    "X-Client-Ip": "2600:1700:4fa6:1a00:2051:938:7373:5563",
  }
}

​
Adding headers to an HTTP response

The following Traffic Policy configuration will add headers to the response from the upstream service when the method is GET and the URL starts with /status/200.

​
Example Traffic Policy Document

on_http_response:
  - expressions:
      - "req.method == "GET" && req.url.path.startsWith("/status/200")"
    actions:
      - type: "add-headers"
        config:
          headers:
            x-custom-header: "my-custom-value"
            x-string-interpolation-example: "started at ${conn.ts.start}"
For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org and we will be adding two headers:
  • x-custom-header with the value my-custom-value
  • x-string-interpolation-example with the value started at ${conn.ts.start} to demonstrate the use of CEL interpolation to include the request connection start time.

​
Example Request

$ curl -i https://httpbin.ngrok.app/status/200

HTTP/2 200 OK
x-custom-header: my-custom-value
x-string-interpolation-example: started at 2024-07-13T00:10:16Z

​
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.
​
actions.ngrok.add_headers.headers_added
object

Map of headers that were added by the action.