What is the Header Matcher?

The Header matcher allows you to create rules that match requests based on HTTP headers. HTTP headers contain metadata about the request or response, such as content type, browser information, authentication credentials, and caching directives.

How Header Matcher Works

The Header matcher evaluates the HTTP headers in the incoming request. You can match requests based on the presence, absence, or specific values of one or more headers.

Common HTTP headers you might want to match include:

User-Agent: Browser or client information
Authorization: Authentication credentials
Accept-Language: Preferred languages
Referer: Page that linked to the current request
Cookie: Cookie data
Content-Type: Format of the request body
X-Forwarded-For: Client IP address (when behind a proxy)

Available Operators

The Header matcher supports these comparison operators for each header:

Operator	Description	Example
`is`	Exact header value match	`Content-Type: application/json` matches only that exact content type
`is_not`	Header value does not match exactly	`User-Agent: Googlebot` matches any request where `User-Agent` is not `Googlebot`
`starts_with`	Header value begins with the specified text	`Accept-Language: en` matches `en-US`, `en-GB`, etc.
`ends_with`	Header value ends with the specified text	`User-Agent: Chrome` matches if `User-Agent` ends with `Chrome`
`contains`	Header value contains the specified text	`User-Agent: mobile` matches if `User-Agent` contains `mobile`
`does_not_contain`	Header value does not contain the specified text	`User-Agent: bot` matches requests where `User-Agent` does not contain `bot`
`has_any_value`	Header exists (any non-empty value)	Matches when the header exists, regardless of value
`is_unknown`	Header does not exist	Matches when the specified header is absent from the request

API Reference

When working with Rules through the API, Header matchers are represented in JSON format. This is the same structure used in the API endpoints for creating and updating rules.

{
  "type": "header",
  "header_params": [
    {
      "name": "User-Agent",
      "value": "Mozilla",
      "operator": "contains"
    },
    {
      "name": "Accept-Language",
      "value": "en",
      "operator": "starts_with"
    }
  ]
}

In API requests, this matcher would be included in the matchers array of a rule object:

{
  "name": "English Mozilla Browsers Rule",
  "active": true,
  "matchers": [
    {
      "type": "header",
      "header_params": [
        {
          "name": "User-Agent",
          "value": "Mozilla",
          "operator": "contains"
        },
        {
          "name": "Accept-Language",
          "value": "en",
          "operator": "starts_with"
        }
      ]
    }
  ],
  "handlers": [
    // handlers would go here
  ]
}

For complete API documentation on rules, including how to create and update rules programmatically, refer to our API Documentation.

Configuration Examples

Example 1: Matching Mobile Devices

This matcher will match requests from mobile devices based on the User-Agent header:

In the UI:

In the API:

{
  "type": "header",
  "header_params": [
    {
      "name": "User-Agent",
      "value": "Mobile",
      "operator": "contains"
    }
  ]
}

Example 2: Checking For API Authentication

This matcher will match requests that have an Authorization header:

In the UI:

In the API:

{
  "type": "header",
  "header_params": [
    {
      "name": "Authorization",
      "operator": "has_any_value"
    }
  ]
}

Example 3: Matching Specific Content Types

This matcher will match requests with a JSON content type:

In the UI:

In the API:

{
  "type": "header",
  "header_params": [
    {
      "name": "Content-Type",
      "value": "application/json",
      "operator": "is"
    }
  ]
}

Example 4: Excluding Bot Traffic

This matcher will match requests that don't appear to be from bots:

In the UI:

In the API:

{
  "type": "header",
  "header_params": [
    {
      "name": "User-Agent",
      "value": "bot",
      "operator": "does_not_contain"
    }
  ]
}

Example 5: Combining Multiple Headers

This matcher will match requests that are both from a mobile device AND have JSON content:

In the UI:

In the API:

{
  "type": "header",
  "header_params": [
    {
      "name": "User-Agent",
      "value": "Mobile",
      "operator": "contains"
    },
    {
      "name": "Content-Type",
      "value": "application/json",
      "operator": "is"
    }
  ]
}

Common Use Cases

Here are some popular ways to use the Header matcher:

Device-Specific Content

Serve different content based on device type:

Create a rule with a Header matcher for User-Agent (e.g., contains "Mobile")
Add handlers to serve mobile-optimized content or redirect to a mobile site

API Security

Enforce authentication for API requests:

Create a rule with a Header matcher checking for Authorization header
Add handlers to validate the credentials or reject unauthenticated requests

Content Negotiation

Respond with the appropriate content format:

Create a rule with a Header matcher for the Accept header
Add handlers to serve content in the requested format (JSON, XML, etc.)

Bot Management

Handle bot traffic differently:

Create a rule with a Header matcher for User-Agent containing "bot" or "crawler"
Add handlers to rate-limit, block, or allow specific bot traffic

Geolocation Routing

Route traffic based on country or region:

Create a rule with a Header matcher for CF-IPCountry or X-Geo-Country headers
Add handlers to redirect to region-specific content or apply region-specific settings

Combining with Other Matchers

The Header matcher becomes especially powerful when combined with other matchers:

Header + Path: Apply header-based rules only to specific sections of your site
Header + Method: Check headers only for specific HTTP methods (e.g., POST)
Header + Query: Match requests with specific headers and query parameters

Remember that when multiple matchers are used in a rule, ALL must match to apply the rule (AND logic).

Best Practices

Header names are case-insensitive, but values can be case-sensitive
Be aware that headers can be modified or spoofed by clients
Use contains for User-Agent matching to account for the variety of formats
For security-critical operations, combine header checks with other verification
Remember that some headers might be added, modified, or removed by proxies
Use has_any_value when you only need to check if a header exists
Use is_unknown when you want to match requests that don't have a specific header

Troubleshooting

If your Header matcher isn't working as expected:

Check header names for spelling (e.g., "User-Agent" not "UserAgent")
Verify that you've chosen the correct operator
Use browser developer tools or server logs to confirm the actual header values
Be aware that some headers might be set by proxies or CDNs between the client and your server
Test with simplified header matching first, then add complexity

The Header matcher provides a powerful way to create rules based on HTTP headers. By leveraging this matcher, you can implement sophisticated request handling based on client information, authentication status, content preferences, and many other factors conveyed through headers.

Until next time, keep building!

Need more help? Reach out via the Intercom chat widget and we'll be right with you!