In short. Netlify sends a headers map to the upstream origin for each matching proxy request, while the returned content keeps its response headers.
Definition: Netlify adds custom request headers to a proxied rewrite by putting a
headersmap in a[[redirects]]block in the Netlify configuration file. The map applies to requests sent to the upstream origin for that proxy rule, while the returned content keeps its own response headers.
Key facts
- Netlify defines a rewrite as a redirect rule with status
200; the visitor keeps the original URL while Netlify fetches the target behind the scenes in its rewrites and proxies documentation. - The documented custom-header syntax uses a
headersmap in the Netlify configuration file and sends those headers to another website with every request matching that proxy redirect. - Netlify states that custom headers apply to the request, not the response, so they are not added to the proxied content returned to the site visitor.
- Netlify's redirect options documentation says that
200is the status used for rewrites and proxying, and that the default status for an unspecified redirect rule is301. - Proxy rewrite requests time out after
26seconds, according to the rewrites and proxies documentation.
What configuration adds the header?
Netlify's documentation, last updated 14 July 2025, puts custom headers in the Netlify configuration file syntax. The from path selects the incoming route, to names the upstream origin, and status 200 keeps the operation as a rewrite. The force setting makes the rule take precedence when a file already matches the requested path.
[[redirects]]
from = "/search"
to = "https://api.mysearch.com"
status = 200
force = true
headers = {X-From = "Netlify"}
The headers value is a map, so the example sends the upstream request header X-From: Netlify. The documented feature is shown in a [[redirects]] block, rather than as a response-header rule for files served by the Netlify site.
What is the scope of the header?
The scope follows the proxy redirect rule. A route such as /api/* can proxy to an external service with the matching path suffix represented by :splat; a custom header in that rule would travel with each request handled by the rule. Netlify describes this pattern as proxying site paths to an external API through its CDN.
The matching rule still controls which requests reach the origin. Netlify's redirect options documentation says an asterisk matches anything that follows it and that the redirect engine processes the first matching rule. More specific rules therefore need to appear before broader rules when several rules could match the same path. A local file can also shadow a rewrite unless the rule is forced. In the TOML syntax, force = true is the documented way to force it.
What does the upstream origin receive?
The custom header belongs to the request from Netlify to the other website. Netlify explicitly separates this from the response: custom headers are not applied to content proxied to the site. A response header such as X-Robots-Tag therefore requires response-header configuration at the serving layer, while the headers map in this rule is for information or credentials sent upstream.
The same Netlify page documents signed proxy redirects as a separate request feature. A signed proxy to an external URL sends an HMAC HS256 encoded x-nf-sign header with every proxied request, and the signing option must be specified in the Netlify configuration file. Signed proxy redirects are not supported when proxying from one Netlify application to another.
What limits should be checked?
Netlify documents a 26 second timeout for proxy rewrite requests. The page also says that internal rewrites are limited by default to one hop, so a request cannot proxy from one Netlify site to a second and then to a third in a single request. Rewrites between Netlify sites belonging to different teams are not allowed. These limits concern the proxy operation itself and are separate from the custom request-header map.
Related terms
- How can Netlify sign requests sent through a proxy redirect?
- Which Netlify redirect wins when file and configuration rules overlap?
- How do I set noindex headers on Netlify?
- How do I target Netlify response headers to a directory?
FAQ
Can I put the custom request header in a _redirects file?
The documented custom-header example uses the Netlify configuration file syntax and a [[redirects]] block with a headers map. Use that form for the configuration shown by Netlify.
Will the header appear in the response sent to visitors?
No. Netlify documents custom headers here as request headers sent to the other website. It states that custom headers are not applied to content proxied to the site.
What happens when a local file matches the proxy path?
You can set force = true in the Netlify configuration file. Netlify documents this setting for forcing a redirect when a file matches the URL path.
Sources
Check how a page reads to answer engines. Open the GEO score analyzer