Skip to main content

Add Headers

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.

Use cases​

Using add-headers enables you to:

  • Enrich your upstream service: Add rich contextual features to your upstream services such as language localization, regional pricing, and more by adding geolocation data to the headers of incoming requests.
  • Authentication: Secure upstream services by using Traffic Policy to add authentication headers to requests.
  • Debugging: Add headers to requests and responses to help with debugging and monitoring of your services.

Configuration Reference​

Fields​

  • headersobjectCEL

    Map of header key to header value to be added.

    Minimum 1, Maximum 10.

    Supports CEL Interpolation in header values.

Here's an example add-headers action configured to add a header with a string and a header with an IP Intelligence Variable.

Loading…

See the example on this page for a full traffic policy using this action.

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.

Limitations​

  • 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.

Action Result Variables​

  • actions.ngrok.add_headers.headers_addedobject

    Map of headers that were added by the action.

Example​

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.

You can use one of the following snippets:

Policy​

Loading…

Agent Config​

Loading…

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​

Loading…
Loading…