Add custom HTTP headers through a .htaccess file

269ac00f765508cb74b25d006dbf5bb2

Written by Dennis Nind

Last published at: February 26th, 2019

This tutorial explains how to quickly add custom HTTP headers using a bit of .htaccess. 

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!

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>