This tutorial explains how to quickly add custom HTTP headers using a bit of .htaccess. Estimated 30 seconds to read and add your own custom header.

Hello, custom header

In this tutorial, we’re talking about custom HTTP headers, which look like this:

parameter=value

So when someone or something requests your web page(s), Apache will return your custom header, along with whatever other headers it usually sends. This is useful for many things, especially testing and troubleshooting various types of functionality, both server-side and client-side.

The basic idea

To add a custom header, we use Apache’s versatile Header directive, like so:

Header add Custom-Header "parameter=value"

Here we are doing the following:

• Instructing Apache to add a header named “Custom-Header”
• Setting the header parameter and value to “parameter” and “value”, respectively

That’s all there is to it. If we add that previous example to our site’s root .htaccess file, Apache will send the custom header for every request. To fine-tune that behavior, we can target specific requests using Apache’s Files or Filesmatch. Alternately we can add the directive to any directory by placing it in the directory’s local .htaccess file.

Server request & response

Here is an example of an HTTP request made with the previous custom-header directive in place. The request looks like this:

GET / HTTP/1.1
Host: example.com
User-Agent: Mozilla/5.0 (Macintosh; Intel Mac OS X 10.11; rv:47.0) Gecko/20100101 Firefox/47.0
Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
Accept-Language: en-US,en;q=0.5
Accept-Encoding: gzip, deflate, br
DNT: 1
Connection: keep-alive
Cache-Control: max-age=0

..to which the server responded with the following headers:

HTTP/1.1 200 OK
Server: nginx
Date: Mon, 01 Aug 2016 17:58:14 GMT
Content-Type: text/html; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/5.6.24, PleskLin
strict-transport-security: max-age=63072000; includeSubDomains; preload
Cache-Control: no-cache, no-store, must-revalidate
Pragma: no-cache
Expires: 0
Custom-Header: parameter=value
Content-Language: en

Notice our custom header in the penultimate line, exactly as specified via the site’s root .htaccess file.

Copy/paste examples

A couple of notes regarding proper syntax. Let’s say that we’re adding a custom header via the following code:

Crunchy-Tacos: "taste=delicious"

It’s important to understand that the header name (e.g., “Crunchy-Tacos”) must not contain any spaces or weird characters. Stick with alphanumeric characters and use underscore and hyphens as needed.

The “parameter=value” string (e.g., “taste=delicious”), on the other hand, may include spaces if you quote the string. So these examples are valid:

Crunchy-Tacos: taste=delicious
Crunchy-Tacos: "taste=really delicious"

..but this is not valid and will trigger a 500-level server error:

Crunchy-Tacos: taste=really delicious

So quotes are required only when including spaces in the “parameter=value” string.

Copy/paste examples

To round out this tutorial, here are some examples of adding custom headers via .htaccess.

Add custom headers to all requests

As explained previously, you can add custom headers to all requests by placing the directive in your site’s root .htaccess file.

# add custom header to all requests
Crunchy-Tacos: "taste=delicious"

Add custom headers to a single file

To add a custom header to a single file or resource, we can use the Files directive, like so:

# add custom header to single file
<Files example.html>
	Crunchy-Tacos: "taste=delicious"
</Files>

Add custom headers to multiple files

To add a custom header to multiple files or resources, we can use the Files directive with a regular expression, like so:

# add custom header to multiple files
<Files ~ "\.(jpe?g|png|gif|mp3|wav|ogg|m4a|mp4|mov|wmv|avi)$">
	Crunchy-Tacos: "taste=delicious"
</Files>

Alternately we can use Apache’s FilesMatch directive:

# add custom header to multiple files
<FilesMatch "\.(jpe?g|png|gif|mp3|wav|ogg|m4a|mp4|mov|wmv|avi)$">
	Crunchy-Tacos: "taste=delicious"
</FilesMatch>

Add custom headers via Apache’s configuration file

We can also add custom headers to any file or resource using Apache’s <Location> or <Directory> directives in httpd.conf.

Learn more..

That should be enough to get you started with adding custom headers via .htaccess. It’s a super-useful technique to have in your web-dev toolbelt. If you found this tutorial useful, you may want to check out my book, .htaccess made easy. It shows you how to optimize and secure your site with .htaccess, and is packed full of awesome tutorials, techniques, tricks and tips.