Header Matcher

The Header matcher allows a rule to match requests based on HTTP request headers. It is the primary way to create behavior that depends on client information, authentication state, content type, or any other metadata carried in headers.

The Header matcher only determines whether a rule should run. Once a request matches, the rule’s configured handlers execute.

To learn how rules work, see Hostgrid Rules.

The Header matcher evaluates the headers of the incoming request. You specify which header to inspect and what condition its value must satisfy.

For the request:

GET /dashboard HTTP/1.1
Host: example.com
Authorization: Bearer token_abc123
User-Agent: Mozilla/5.0 (iPhone; CPU iPhone OS 17_0 like Mac OS X)
Accept-Language: en-US
Content-Type: application/json

The components are:

Only the specified header is evaluated by this matcher. The path, method, and query parameters are matched using their own matcher types.

Any standard or custom header can be matched.

The Header matcher supports the following comparison operators.

These operators perform string comparisons against the header value. Choose the operator that most closely matches the requests you want the rule to affect.

To match requests from mobile devices:

Header: User-Agent
Operator: contains
Value: Mobile

API representation:

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

To match requests using Bearer token authentication:

Header: Authorization
Operator: begins with
Value: Bearer

API representation:

{
    "type": "header",
    "params": {
        "items": [
            {
                "name": "Authorization",
                "operator": "begins_with",
                "value": "Bearer"
            }
        ]
    }
}

This matches any request where the Authorization header starts with Bearer, regardless of the token value that follows.

To match requests with a JSON body:

Header: Content-Type
Operator: is equal to
Value: application/json

API representation:

{
    "type": "header",
    "params": {
        "items": [
            {
                "name": "Content-Type",
                "operator": "equal",
                "value": "application/json"
            }
        ]
    }
}

To match requests that do not appear to come from bots:

Header: User-Agent
Operator: does not contain
Value: bot

API representation:

{
    "type": "header",
    "params": {
        "items": [
            {
                "name": "User-Agent",
                "operator": "not_contains",
                "value": "bot"
            }
        ]
    }
}

A single Header matcher can include conditions for more than one header.

When multiple header conditions are added to the same matcher, all of them must match before the rule executes.

For example, a single Header matcher with these conditions:

User-Agent contains Mobile
Content-Type is equal to application/json

Only matches requests that satisfy both conditions — a mobile client sending JSON.

This is different from adding two separate Header matchers to the same rule, which behaves identically. Use whichever approach keeps your rule configuration clearer.

A rule can contain matchers of different types. When multiple matchers are configured, all of them must match before the rule executes.

Similarly, you can combine the Header matcher with:

• Path Matcher
• Method Matcher
• Query Matcher

The Header matcher is most effective when paired with a handler that takes a different action based on the headers in the request.

• Header names are case-insensitive, but values may be case-sensitive depending on the header specification. The matcher performs case-sensitive value comparisons.
• Use contains or begins with for User-Agent matching. User-Agent strings are long and vary across versions. Exact matching is fragile.
• Use begins with instead of is equal to for Content-Type when the header may include parameters like charset.
• Do not rely on headers for security-critical decisions. Headers such as User-Agent, Referer, and X-Forwarded-For can be set or modified by clients and intermediaries.
• Be aware of proxy and CDN behavior. Proxies may add, modify, or remove headers before the request reaches Hostgrid.
• Use unknown when the header should not affect matching. This is useful when the matcher is included for organizational clarity but the rule should run regardless of the header value.

If a rule with a Header matcher is not matching as expected:

• Check header name spelling. Use the standard format with hyphens (e.g., User-Agent, not UserAgent or user-agent). Names are matched case-insensitively.
• Verify the actual header value. Use browser developer tools (Network tab) to inspect the exact value being sent. Values may include unexpected whitespace, charset parameters, or version strings.
• Review operator selection. is not equal to application/json matches every other content type including text/html and multipart/form-data — not just “no content type.”
• Check for proxy interference. If your traffic passes through a CDN or proxy, headers may be added, removed, or rewritten before reaching Hostgrid.
• Confirm matcher combinations. If the rule has multiple matchers, every one must evaluate to true. A Path matcher that does not match will prevent the rule from running even if the Header matcher does.
• Consider rule order. If an earlier rule contains a Redirect or Static Response handler, later rules will not execute for that request.

For more information about rule evaluation, see Hostgrid Rules.

• Hostgrid Rules
• Path Matcher
• Method Matcher
• Query Matcher
• Rule Handlers