New Safari extension: ChangeTheHeaders to customize HTTP request headers

March 27, 2025
By Jeff Johnson of Underpass App Company

I’m happy to announce that I’ve just released a new app! ChangeTheHeaders is a Safari extension for iOS, iPadOS, macOS, and visionOS that allows you to customize HTTP request headers such as Accept, Accept-Language, Cookie, and User-Agent. ChangeTheHeaders is available now in the App Store.

I owe the idea for ChangeTheHeaders—as well as its name—to John Gruber of Daring Fireball. John came to me with a Safari problem, presumably because I’m the person who claims to stop the madness in Safari. John was wondering why dragging an image to Finder directly from a web page (content warning: political) produced a WebP file, whereas dragging the image opened in a new Safari tab produced a PNG file. That is puzzling! After some investigation, I discovered that the difference was the Accept HTTP request header, which specifies what types of response the web browser will accept. Safari’s default Accept header for images is this:

Accept: image/webp,image/avif,image/jxl,image/heic,image/heic-sequence,video/*;q=0.8,image/png,image/svg+xml,image/*;q=0.8,*/*;q=0.5

Although image/webp appears first in the list, the order actually doesn’t matter. The quality value, specified by the ;q= suffix, determines the ranking of types. The range of values is 0 to 1, with 1 as the default value if none is specified. Thus, image/webp and image/png have equal precedence, equal quality value 1, leaving it up to the web site to decide which image type to serve. In this case, the web site decided to serve a WebP image, despite the fact that the image URL has a .png suffix. In a URL, unlike in a file path, the “file extension”, if one exists, is largely meaningless. A very simple web server will directly match a URL with a local file path, but a more complex web server can do almost anything it wants with a URL.

What happens when you select “Open Image in New Tab” from the Safari contextual menu? The name of the contextual menu item is slightly misleading, because Safari doesn’t use the already loaded image but rather loads the image URL anew in a new tab. Moreover, for some reason, Safari uses a different Accept header in this case:

Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8

Given a different request header, the web site decided to return a different image type, PNG. Don’t ask me why, because I don’t know! Again, image/webp and image/png have equal precedence here, so you could receive either one (or some other image type). This is what computer programmers call “undefined behavior”.

You now have my typically long-winded explanation of the problem, but what’s my solution to the problem? The behavior is caused by the Accept header, so if you want to change the behavior, you have to change the header, and while Safari itself has no settings to change its HTTP request headers, it does provide that capability to Safari extensions, which is where I come in. I considered and rejected the idea of a “stop the webp images” extension as far too niche for a product. However, some StopTheMadness Pro customers have requested similar features, such as the ability to spoof the User-Agent header. Thus, I decided to make a Safari extension that can customize any HTTP request headers, in the hope that a market exists for it. (Alas, Safari does not allow customization of HTTP response headers too.)

You might ask, why didn’t I just add this feature to StopTheMadness Pro? On macOS, StopTheMadness Pro is a Safari app extension, but the API to modify HTTP headers is available only to Safari web extensions, unfortunately. This is the same reason that StopTheMadness Pro doesn’t currently support Safari web apps.

Originally, my name for the new Safari extension was the unimaginative Override Headers. As the old saying goes, there are only two hard things in computer science, and one of them is naming things. When I told John Gruber that I had trouble coming up with a good name for the extension, he immediately brainstormed ChangeTheHeaders, riffing on my theme of StopTheMadness, StopTheScript, StopTheFonts, etc. I liked and indeed preferred his suggestion, but the app was practically done already (or so I believed at the time). It already had an app icon, based on the old app name. On the other hand, that app icon was amateurish and poorly designed… by me! So I turned once again to a true professional, Matthew Skiles, for a new app icon, based on the new name. I tip my hat to Matt!

What can you do with ChangeTheHeaders? I suspect the biggest selling point will be to spoof the User-Agent. The extension allows you to customize your User-Agent by URL domain. For example, you can make Safari pretend that it’s Chrome on Google web apps that give special treatment to Chrome. You can also customize the Accept-Language header if you don’t like the default language handling of some website, such as YouTube. (Why is the problem on the web always Google?) Or if you just want to deprioritize WebP images in Safari, you can do that, of course. It’s a simple matter of removing image/webp from the list. You probably don’t want to stop WebP entirely, because it may be the only image type available on some websites, but if you remove image/webp from the Accept header, then it no longer has the default quality value of 1. Instead, image/webp would fall under the wildcard image/*;q=0.8 specification, with a lower priority than explicit image types such as image/png. More information on how to configure ChangeTheHeaders is in the fine manual.

I hope that you find ChangeTheHeaders useful. Get it now in the App Store!