Skip to main content

Add Headers

Overview​

The Add Headers Traffic Policy action enables you to add headers to an HTTP request before it is sent upstream or an HTTP response before it is sent back to the client.

Configuration Reference​

This is the Traffic Policy configuration reference for this action.

Action Type​

add-headers

Configuration Fields​

ParameterTypeDescription
headersmap[string]stringMap of header key to header value to be added. Minimum 1, Maximum 10. Supports CEL Interpolation in header values.

Supported Phases​

  • on_http_request
  • on_http_response

Supported Schemes​

  • https
  • http

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.

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.

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.

NameTypeDescription
actions.ngrok.add_headers.headers_addedmap[string]stringThe headers and associated values that were added by the action.