Skip to content
Cloudflare Docs

Request Header Transform Rules

Use Request Header Transform Rules to manipulate the headers of HTTP requests sent to your origin server.

flowchart LR
accTitle: Header modifications diagram
accDescr: Header transform rules can change the headers sent to your origin server (request header modifications) or sent your your website visitors (response header modifications).

A[Visitor]
B((Cloudflare))
C[(Origin server)]

A -.-> B == "Includes request<br> header modifications" ==> C
C -.-> B -. "Includes response<br> header modifications" .-> A

style A stroke-width: 2px
style B stroke: orange,fill: orange,color: black
linkStyle 0,2,3 stroke-width: 1px
linkStyle 1 stroke-width: 3px

To modify HTTP headers in the response sent to website visitors, refer to Response Header Transform Rules.

Through Request Header Transform Rules you can:

  • Set the value of an HTTP request header to a literal string value, overwriting its previous value or adding a new header to the request.
  • Set the value of an HTTP request header according to an expression, overwriting its previous value or adding a new header to the request.
  • Remove an HTTP header from the request.

You can create a request header transform rule in the dashboard, via API, or using Terraform.

For more complex request header modifications, consider using Snippets.

Important remarks

  • You cannot modify or remove HTTP request headers whose name starts with x-cf- or cf- except for the cf-connecting-ip HTTP request header, which you can remove.

  • Due to protocol compliance reasons, modifying or removing request headers with forbidden header names ↗ (such as Accept-Encoding) is generally not allowed in Request Header Transform Rules.

  • You cannot modify the value of any header commonly used to identify the website visitor's IP address or initial protocol, such as x-forwarded-for, true-client-ip, x-real-ip, or x-forwarded-proto. Additionally, you cannot remove the x-forwarded-for and x-forwarded-proto headers.

  • You cannot set or modify the value of cookie HTTP request headers, but you can remove these headers. Configuring a rule that removes the cookie HTTP request header will remove all cookie headers in matching requests.

  • If you modify the value of an existing HTTP request header using an expression that evaluates to an empty string ("") or an undefined value, the HTTP request header is removed.

  • The HTTP request header removal operation will remove all request headers with the provided name.

  • Currently, there is a limited number of HTTP request headers that you cannot modify. Cloudflare may remove restrictions for some of these HTTP request headers when presented with valid use cases. Create a post in the community ↗ for consideration.

  • To use claims inside a JSON Web Token (JWT), you must first set up a token validation configuration in API Shield.

  • Request header transform rules run in order, and later rules can overwrite changes done by previous rules.

  • The values of request and response fields are immutable within each phase, such as the http_request_late_transform phase where request header transform rules are defined. This means that later request header transform rules will not match based on changes done by previous request header transform rules. Refer to Field values during rule evaluation for more information.

Execution order

The execution order of Rules features is the following:

The different types of rules listed above will take precedence over Page Rules. This means that Page Rules will be overridden if there is a match for both Page Rules and the Rules products listed above.

Generally speaking, for non-terminating actions the last change made by rules in the same phase will win (later rules can overwrite changes done by previous rules). However, for terminating actions (Block, Redirect, or one of the challenge actions), rule evaluation will stop and the action will be executed immediately.

For example, if multiple rules with the Redirect action match, Cloudflare will always use the URL redirect of the first rule that matches. Also, if you configure URL redirects using different Cloudflare products (Single Redirects and Bulk Redirects), the product executed first will apply, if there is a rule match (in this case, Single Redirects).

Refer to the Phases list for the product execution order.

Troubleshooting

When troubleshooting Request Header Transform Rules, use Cloudflare Trace to determine if a rule is triggering for a specific URL.