What is the Set Response Header Handler?
The Set Response Header Handler allows you to add new HTTP headers or modify existing ones in responses before they're delivered to the client. Headers play a crucial role in HTTP communication, controlling aspects like caching, security policies, and cross-origin resource sharing. With this handler, you can implement these controls without modifying your upstream server's configuration.
How Set Response Header Handler Works
When a rule with a Set Response Header Handler matches an incoming request, the handler adds or modifies the specified headers in the response after it's received from your upstream server but before it's sent to the client. If a header with the same name already exists in the response, this handler will replace its value. If the header doesn't exist, it will be added.
This process is transparent to both your upstream server and the end user, allowing you to implement header-based functionality without changing your application code.
Configuration Options
The Set Response Header Handler requires a list of headers to set:
Option | Type | Required | Description |
|
| Yes | An array of header objects to add or modify in the response |
Each replacement object within the array has these properties:
Property | Type | Required | Description |
|
| Yes | The name of the header (case-insensitive, but conventional format is hyphenated with initial capitals) |
|
| Yes | The value to set for the header |
API Reference
When working with Rules through the API, Set Response Header handlers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.
{
"type": "set_response_header",
"headers": [
{
"name": "X-Custom-Header",
"value": "custom-value"
},
{
"name": "Cache-Control",
"value": "max-age=3600"
}
]
}In API requests, this handler would be included in the handlers array of a rule object:
{
"name": "Add Security Headers Rule",
"active": true,
"matchers": [],
"handlers": [
{
"type": "set_response_header",
"headers": [
{
"name": "Strict-Transport-Security",
"value": "max-age=31536000; includeSubDomains"
},
{
"name": "X-Content-Type-Options",
"value": "nosniff"
}
]
}
]
}
Configuration Examples
Example 1: Adding Security Headers
This handler will add essential security headers to all responses:
In the UI:
In the API:
{
"type": "set_response_header",
"headers": [
{
"name": "X-Frame-Options",
"value": "SAMEORIGIN"
},
{
"name": "Content-Security-Policy",
"value": "default-src 'self'"
}
]
}
Example 2: Configuring Cache Control
This handler will set caching directives for static assets:
In the UI:
In the API:
{
"type": "set_response_header",
"headers": [
{
"name": "Cache-Control",
"value": "max-age=604800, public"
}
]
}This example helps browsers cache static content for one week, improving load times for returning visitors.
Example 3: Redirecting to a New Location
This handler, when combined with a Static Response, creates a redirect:
In the UI:
In the API:
{
"type": "set_response_header",
"headers": [
{
"name": "Location",
"value": "https://new-location.example.com/updated-page"
}
]
}When used with a Static Response handler with status code 301 or 302, this will redirect users to the specified URL.
Common Use Cases
Here are some popular ways to use the Set Response Header Handler:
Enhancing Security
Implement modern security policies through headers:
Add HSTS headers to enforce HTTPS usage
Configure Content-Security-Policy to prevent XSS attacks
Set X-Frame-Options to prevent clickjacking
Add X-XSS-Protection headers for older browsers
Implement Feature-Policy to control browser features
Optimizing Caching
Control how browsers and CDNs cache your content:
Set Cache-Control headers for different content types
Add ETag headers for validation
Configure Expires headers for absolute expiration times
Use Vary headers to control cache variations
Implement stale-while-revalidate directives for optimal performance
Managing Cross-Origin Requests
Control how your resources are accessed across domains:
Configure Access-Control-Allow-Origin for permissible domains
Set Access-Control-Allow-Methods for allowed HTTP methods
Define Access-Control-Allow-Headers for acceptable headers
Add Access-Control-Max-Age to cache preflight requests
Support Access-Control-Allow-Credentials for authenticated requests
Implementing Redirects
Direct users to new locations without server configuration:
Set Location headers with destination URLs
Combine with Static Response handler using 301 (permanent) or 302 (temporary) status codes
Create conditional redirects based on complex path or query matching
Adding Custom Headers for Analytics
Pass additional information to analytics tools and services:
Add server-timing headers for performance tracking
Include custom headers with A/B test variations
Pass user segment information to edge analytics
Add tracking identifiers without client-side scripts
Setting Content Type and Encoding
Ensure proper content interpretation:
Set Content-Type headers for proper MIME type recognition
Add Content-Encoding for compression information
Set Charset parameters for text content
Configure Content-Language headers for internationalization
Combining with Other Handlers
The Set Response Header handler works well when combined with:
Static Response Handler: Add headers to static responses, especially for redirects
Rewrite Handler: Change the request destination and adjust headers accordingly
Replace Response Handler: Modify content and update headers to match
Delete Response Header Handler: Remove unwanted headers before adding new ones
The Set Response Header handler can be placed at different positions in your handler chain depending on your needs:
Before a Static Response handler to add headers to the custom response
After a Replace Response handler if the headers depend on the modified content
After a Delete Response Header handler to ensure clean header replacement
Best Practices
Use standard header names and formats where possible
Follow header naming conventions (hyphenated with initial capitals, like "Content-Type")
Be aware that header names are case-insensitive but values may be case-sensitive
Document your custom headers, especially for internal or debugging purposes
Test with different browsers to ensure compatibility
Keep header values reasonably sized (some servers reject very large headers)
Use a separate handler for security headers to make management easier
Be mindful of header interactions and conflicts
Follow specifications for standard headers to avoid unexpected behavior
Troubleshooting
If your Set Response Header handler isn't working as expected:
Verify that your matchers are correctly identifying the requests
Check for conflicts with headers already set by your upstream server
Ensure header values follow the correct format for each header type
Use browser developer tools to inspect the actual headers received
Check for any response code conditions that might affect header processing
Verify that header names don't contain invalid characters
Remember that some headers have restricted usage (e.g., Set-Cookie has specific requirements)
Test with different clients to ensure cross-browser compatibility
Limitations
Some headers have special handling in browsers and might not behave as expected
Certain headers can only be set by the browser (e.g., Cookie) and not by servers
Headers added by this handler will override those from your upstream server with the same name
Very long header values may be truncated by some proxies or clients
Some security headers require careful configuration to avoid breaking functionality
Cookies require specific formatting and attributes when using the Set-Cookie header
The Set Response Header handler provides powerful control over HTTP communication between your servers and clients. By strategically adding and modifying headers, you can enhance security, optimize performance, and enable advanced web functionality without changing your application code.
Until next time, keep building!
Need more help? Reach out via the Intercom chat widget and we'll be right with you!