To intercept HTTP requests, use the {{WebExtAPIRef("webRequest")}} API. This API enables you to add listeners for various stages of making an HTTP request. In the listeners, you can:
- get access to request and response headers and bodies
- cancel and redirect requests
- modify request and response headers
In this article we'll look at three different uses for the webRequest module:
- Logging request URLs as they are made.
- Redirecting requests.
- Modifying request headers.
Logging request URLs
Create a new directory called "requests". In that directory, create a file called "manifest.json" which has the following contents:
{
"description": "Demonstrating webRequests",
"manifest_version": 2,
"name": "webRequest-demo",
"version": "1.0",
"permissions": [
"webRequest"
],
"background": {
"scripts": ["background.js"]
}
}
Next, create a file called "background.js" with the following contents:
function logURL(requestDetails) {
console.log("Loading: " + requestDetails.url);
}
chrome.webRequest.onBeforeRequest.addListener(
logURL,
{urls: ["<all_urls>"]}
);
Here we use the {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} event listener. Just before each request is made, the logURL() function is run, which grabs the URL of the request from the event object and logs it to the browser console, prefixed by "Loading: ". The {urls: ["<all_urls>"]} pattern means we will intercept HTTP requests to all URLs.
Now install the WebExtension, open the Browser Console, and open some Web pages. In the Browser Console, you should see the URLs for any resources that the browser requests:
{{EmbedYouTube("X3rMgkRkB1Q")}}
Redirecting requests
Now let's use webRequest to redirect HTTP requests. First, replace manifest.json with this:
{
"description": "Demonstrating webRequests",
"manifest_version": 2,
"name": "webRequest-demo",
"version": "1.0",
"permissions": [
"webRequest", "webRequestBlocking"
],
"background": {
"scripts": ["background.js"]
}
}
The only change here is to add the "webRequestBlocking" permission. We need to ask for this extra permission whenever we are actively modifying a request.
Next, replace "background.js" with this:
var pattern = "https://mdn.mozillademos.org/*";
function redirect(requestDetails) {
console.log("Redirecting: " + requestDetails.url);
return {
redirectUrl: "https://38.media.tumblr.com/tumblr_ldbj01lZiP1qe0eclo1_500.gif"
};
}
chrome.webRequest.onBeforeRequest.addListener(
redirect,
{urls:[pattern], types:["image"]},
["blocking"]
);
Again, we use the {{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}} event listener to run a function just before each request is made. This function will replace the target URL with the redirectUrl specified in the function.
This time we are not intercepting every request: the {urls:[pattern], types:["image"]} option specifies that we should only intercept requests (1) to URLs residing under "https://mdn.mozillademos.org/" (2) for image resources.
Also note that we're passing an option called "blocking": we need to pass this whenever we want to modify the request. It makes the listener function block the network request, so the browser waits for the listener to return before continuing. See the {{WebExtAPIRef("webRequest.onBeforeRequest")}} documentation for more on "blocking".
Now open a page on MDN that contains a lot of images (for example https://developer.mozilla.org/en-US/docs/Tools/Network_Monitor), reload the WebExtension, and then reload the MDN page:
{{EmbedYouTube("ix5RrXGr0wA")}}
Modifying request headers
Finally we'll use webRequest to modify request headers. In this example we'll modify the "User-Agent" header so the browser identifies itself as Opera 12.16, but only when visiting pages under https://useragentstring.com/".
The "manifest.json" can stay the same as in the previous example.
Replace "background.js" with code like this:
var targetPage = "https://useragentstring.com/*";
var ua = "Opera/9.80 (X11; Linux i686; Ubuntu/14.10) Presto/2.12.388 Version/12.16";
function rewriteUserAgentHeader(e) {
for (var header of e.requestHeaders) {
if (header.name == "User-Agent") {
header.value = ua;
}
}
return {requestHeaders: e.requestHeaders};
}
chrome.webRequest.onBeforeSendHeaders.addListener(
rewriteUserAgentHeader,
{urls: [targetPage]},
["blocking", "requestHeaders"]
);
Here we use the {{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}} event listener to run a function just before the request headers are sent for each request. This function will intercept requests made only for the URL specified in the targetPage variable (see the {urls: [targetPage]} pattern), find the "User-Agent" header from inside the requestHeaders property of the event object, and replace it with the value found in the ua variable.
Now open useragentstring.com and check that it identifies the browser as Firefox. Then reload the add-on, reload useragentstring.com, and check that Firefox is now identified as Opera:
{{EmbedYouTube("SrSNS1-FIx0")}}
Learn more
To learn about all the things you can do with the webRequest API, see its reference documentation.