Skip to content
Cloudflare Docs
Docs DirectoryAPIsSDKs

Response Header Transform Rules

Use Response Header Transform Rules to manipulate the headers of HTTP responses sent to website visitors.

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,1,2 stroke-width: 1px
linkStyle 3 stroke-width: 3px

To modify HTTP headers in the request sent to your origin server, refer to Request Header Transform Rules.

Through Response Header Transform Rules you can:

  • Set the value of an HTTP response header to a literal string value, overwriting its previous value or adding a new header to the response if it does not exist.
  • Set the value of an HTTP response header according to an expression, overwriting its previous value or adding a new header to the response if it does not exist.
  • Add a new HTTP response header with a literal string value without removing any existing headers with the same name.
  • Add a new HTTP response header according to an expression without removing any existing headers with the same name.
  • Remove an HTTP header from the response.

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

For more complex response header modifications, consider using Snippets.

Important remarks

  • The response header values are calculated using the field values from the corresponding HTTP request. For example, the field ip.src.country (used in expressions) will return the country of the website visitor, not the country of the origin server where the response was sent from.

  • You cannot add, modify, or remove HTTP response headers whose name starts with cf- or x-cf-.

  • You cannot modify the value of certain headers such as server, eh-cache-tag, or eh-cdn-cache-control.

  • Currently you cannot reference IP lists in expressions of Response Header Transform Rules.

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

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

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

  • Response header transform rules will also apply to default Cloudflare error pages and Custom Errors.

  • Modifying cache-control, CDN-Cache-Control, or Cloudflare-CDN-Cache-Control headers using response header transform rules will not change the way Cloudflare caches an object, because Cloudflare evaluates caching behavior before applying response header modifications. To control Cloudflare cache behavior, create a cache rule.

  • To add a set-cookie header to the response, use one of the Add static/Add dynamic operations instead of Set static/Set dynamic. Add operations append a new header without removing existing headers of the same name, while Set operations replace all existing headers of that name. Using a Set operation for set-cookie will remove any set-cookie headers already in the response, including those added by other Cloudflare products such as Bot Management.

  • Response 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_response_headers_transform phase where response header transform rules are defined. This means that later response header transform rules will still use the original field values when evaluating their filter expressions, not the values changed by previous rules. Refer to Field values during rule evaluation for more information.

Troubleshooting

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