Modify Cache Key in Akamai based upon Request Header Value

A cache key is a unique string that lets Akamai edge servers look for your content when requests hit them. It’s made up of a few different pieces (like origin hostname, path, and filename).

By default cache key doesn’t include request headers value but you might want to cache & serve different content based upon the value of a particular request header. For example, serving a webp image if the browser supports WebP format by specifying image/webp in the Accept header value. We will discuss two ways to modify cache key in Akamai.

Using Cache ID modification module

This method is the easiest way to modify cache key. It takes the cache control options for setting the cache key beyond just path, filename, and query parameters by adding header or cookie values to the mix. Since this is only available with the inclusion of Advanced Cache Optimization module, therefore we will discuss the second technique which always works!

Using Variables and Modify outgoing request path behavior

Let’s cover it with an example. Suppose you want to serve WebP image on a particular request if Accept header value has image/webp in it.

Accept header value has image/webp in Chrome

Follow the below steps to modify cache key without using Cache-ID modification

1. Create a property variable e.g. IS_WEBP and assign it a initial value false

Create a property variable IS_WEBP with initial value: false

You can learn more about property variables from here. But for now, the above screenshot contains enough information to create a variable IS_WEBP with a initial value false.

2. Update value of IS_WEBP variable based upon Accept header value.

Update IS_WEBP value based upon Accept header value

3. Make sure that you have checked “Allow wildcards in value” under additional settings of If match criteria.

Allow wildcards in value

Since the value of Accept header can be: image/webp,image/apng,image/*,*/*;q=0.8, so we match on *image/webp*. By default wildcards are not allowed and matched so remember to check this field.

4. Modify outgoing request path to include this variable value

Modify outgoing request path to include IS_WEBP value

How to check if cache is being modifed based upon different Accept header values

We can easily see the value of various debug headers that Akamai sets for a request. You can use this plugin: Akamai debug headers.

I am showing an example request on

In Chrome notice that value of X-True-Cache-Key contains $$IS_WEBP=true$$.

Variable value included in cache key

Similarly, if you issue the same request in FireFox, you should see $$IS_WEBP=false$$ in the cache key field.

Hence we have successfully modified the cache key based upon the value of Accept request header. And now Akamai will serve & cache different copies at the same URL.

However, this method poses an altogether new problem by prepending $$IS_WEBP=true|false$$ in the path.

So for example, if your original image is at below path.


If Akamai receives a request for this image from Chrome, then Akamai will hit your origin server www.example.cow at below endpoint

You need to ignore everything including $$…$$. You can easily do that with Varnish like this:
if (req.url ~ "\$\$IS_WEBP=") {
        set req.url = regsub( req.url, "/\$\$IS_WEBP=true\$\$/", "/");
        set req.url = regsub( req.url, "/\$\$IS_WEBP=false\$\$/", "/");

Reach out to us at if you have any questions or suggestions.