Headerbench

Headerbench documentation

Getting started

  1. Install Headerbench. Chrome shows no permission warning, because it asks for no sites yet.
  2. On the welcome page, import a ModHeader export or start with a blank profile. A profile is a named set of rules: headers, filters, redirects, blocks and (Pro) mocks.
  3. Add a request header, for example X-Debug: 1, and a filter such as the domain api.staging.example.com.
  4. Turn the profile on in the popup, on the page you are testing. Headerbench asks Chrome for access to the sites the profile changes and that page; accept Chrome’s prompt.
  5. Reload your page and open the popup. Applied on this tab lists what ran.

Profiles and priority

Several profiles can be on at once. Their order in the popup is their priority: when two profiles set the same header on the same request, the one higher in the list wins. Drag to reorder.

  • This tab only applies a profile to the tab you turned it on in. Chrome forgets tab ids on restart, so tab-only activations end when the browser closes.
  • Auto-pause turns a profile off after 1 or 8 hours.
  • Pause all (popup switch, or Alt+Shift+H) stops every rule without changing your profiles.
  • Profiles tagged prod ask for confirmation before they turn on.

Request headers

Each row sets, appends or removes one header. Set replaces any value the browser would send; remove drops the header; append adds to the existing value.

Chrome only allows append on these request headers: Accept, Accept-Encoding, Accept-Language, Access-Control-Request-Headers, Cache-Control, Connection, Content-Language, Cookie, Forwarded, If-Match, If-None-Match, Keep-Alive, Range, TE, Trailer, Transfer-Encoding, Upgrade, User-Agent, Via, Want-Digest and X-Forwarded-For. Headerbench turns an append on any other header into a set and tells you so.

Header names must be valid HTTP tokens and values cannot contain line breaks. A row that fails these checks is skipped with an inline message; the rest of the profile still runs.

Response headers

Response rows work the same way and change what the page sees, for example Access-Control-Allow-Origin or Cache-Control. Two presets add common sets in one click:

  • Allow CORS sets Access-Control-Allow-Origin, -Methods, -Headers and -Credentials. Browsers ignore * as the origin when the request carries cookies; use your app’s origin, such as http://localhost:3000, instead.
  • Remove Content Security Policy removes Content-Security-Policy and its report-only variant. A policy set in a <meta> tag inside the page still applies.

Filters

Without filters, a profile applies to every site it has access to. Add filters to narrow it:

  • Domain: example.com matches the domain and its subdomains.
  • URL pattern (Chrome’s urlFilter syntax): || anchors to a domain, | to the start or end of the URL, ^ matches a separator such as / or ?, and * matches anything. Example: ||api.example.com/v2/.
  • Regex: Chrome uses RE2, so lookahead, lookbehind and backreferences are not available.
  • Exclude: any filter can exclude instead of include. Pattern and regex excludes also pause lower-priority profiles on the matching URLs.
  • Request types and methods: limit a profile to, say, fetch/XHR and POST. With none selected, every type is included, page loads too.

Redirects and blocks

  • Redirect an exact URL or a URL pattern to another URL. Redirects use their own pattern, not the profile’s filters.
  • Block requests matching a pattern, for example a third-party script.
  • Regex redirects (Pro) rewrite with capture groups: ^https://cdn\.example\.com/(.*)$ to http://localhost:8080/\1.

Mock responses (Pro)

A mock returns a fixed body with the content type you choose, such as application/json, for requests matching its pattern. Chrome serves it as a redirect to a data: URL, so:

  • the status is always 200, and response headers from the real server are not sent;
  • bodies are limited to 64 KB;
  • mocks apply to fetch/XHR, scripts, stylesheets, images, fonts and media, but not to page or iframe navigations, which Chrome won’t load from a data: URL.

Variables (Pro)

Define token once and write {{token}} in any header value, redirect target or mock body. Changing the variable updates every rule that uses it. Without Pro, the text stays as written and the editor flags it.

Test a URL and Applied on this tab

Test a URL takes a URL, request type and method and lists every rule that would apply, which profile it comes from, and warnings such as missing site access or a higher-priority profile overriding a header.

Applied on this tab in the popup asks Chrome which rules actually ran on the current tab. Chrome DevTools may not show headers changed by extensions, so use this view to confirm.

Chrome limits

  • Chrome allows an extension 5,000 header and redirect rules and 1,000 regex rules. Headerbench stops at 4,500 and 900 to stay clear, keeps your previous rules active, and shows the counts. A profile with ten headers is one rule per filter, not ten.
  • Chrome applies header and redirect rules only when Headerbench can access both the request’s site and the page that sends it. Without both, it silently skips them.
  • Tab-only profiles use Chrome session rules, which are cleared when the browser restarts.
  • Headerbench needs Chrome or Edge 128 or later.

Permissions

Headerbench requests these permissions, none of which show a warning at install:

  • declarativeNetRequestWithHostAccess: hands your rules to Chrome, acting only on sites you granted.
  • storage: saves profiles and settings in your browser.
  • activeTab: lets the popup show what applied on the tab you opened it on.
  • alarms: runs auto-pause timers.

Site access is optional. When you turn on a profile, Headerbench asks Chrome for access to the sites that profile changes and the page you’re using it on, nothing more. Chrome needs both: it changes a request from localhost:5173 to api.example.com only if Headerbench can access each. A profile without filters needs access to all sites, and Headerbench says so before asking. If you turn a profile on from the editor, open the popup on the page you are testing to grant that page. Revoke any site from the Permissions page; profiles that need it show Blocked by Chrome: no site access with a button to grant it again.

Import and export

Headerbench imports ModHeader exports (both the original format and the newer clone format) and its own JSON. Every file is checked before anything is saved; if it can’t be read, nothing is imported. The report lists what came across and what was switched off, for example dynamic JavaScript values or regexes Chrome cannot run.

Export writes your profiles and variables to a JSON file. Your licence and settings are never exported. You can also convert a ModHeader file in the browser without installing anything.

Pro licence and trial

  • The 14-day trial starts the first time you save a Pro rule. No card, no account.
  • A licence key is checked offline inside the extension. Yearly keys carry their renewal date plus 7 days of grace; the extension renews them from headerbench.com before they expire. Lifetime keys don’t expire.
  • If Pro lapses, mocks, regex redirects and variables pause. They are not deleted and come back when Pro is active again.
  • Lost your key? Recover it with your receipt email.

Getting help

In Headerbench, Settings → Report a problem opens an email with diagnostics filled in: version, rule counts, warnings and granted sites, for you to review before sending. Or write to support@headerbench.com. Written support, usually within one business day.