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.

Example​

Adding headers to an HTTP response​

The following Traffic Policy configuration:

  • Checks if the request method is GET and the URL starts with /status/200
  • If so, adds the following headers to the response from the upstream service
    • x-custom-header:my-custom-value
    • x-string-interpolation-example:started at ${conn.ts.start} - This header gets its value from CEL interpolation using [IP Intelligence Variables] to include the request connection start time.
Loading…
note

For this example, we are assuming that ngrok is pointing at the upstream service https://httpbin.org.

Example request​

To test the configuration, you could run a curl request similar to the following:

Loading…
Loading…

Configuration reference​

Fields​

  • headersobjectCEL

    Map of header key to header value to be added.

    Minimum 1, Maximum 10.

    Supports CEL Interpolation in header values.

Example configuration​

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.

Action result variables​

These are the variables you can use in subsequent actions after this action has been executed.

  • actions.ngrok.add_headers.headers_addedobject

    Map of headers that were added by the action.

Behavior​

  • on_http_request: When configured in this phase, this action will add the specified headers to incoming http requests before reaching the upstream server.
  • on_http_response When configured in this 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 Limitations for more information.

To replace or remove headers, use remove-headers. You can then add your prefered headers with add-headers.

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.