Firefox 153.0.0: Use the webRequest API for extensions

What You”ll Need

• Firefox 153.0.0 (desktop or compatible developer channel)
• Basic WebExtension scaffolding: manifest.json and a background script (or service worker)
• manifest permissions: webRequest and host permissions for the URLs you will observe (e.g., <all_urls> or specific patterns)
• To modify or block requests: also add webRequestBlocking permission
• Developer tools access (about:debugging) to load and test temporary extensions

How It Works

The webRequest API provides event-based callbacks that fire at key points in a request lifecycle: before the request is made (onBeforeRequest), before headers are sent (onBeforeSendHeaders), after headers are received (onHeadersReceived), onCompleted, onErrorOccurred, and onAuthRequired. Your extension registers listeners in a persistent background script or service worker; the browser invokes those listeners with a details object for each matching request.

Listeners use a filter (URL patterns and resource types) and an extraInfoSpec array to request additional data or blocking capability (for example, requestBody or responseHeaders). When you need to change headers, redirect, or cancel a request, include webRequestBlocking and return the appropriate blocking response synchronously from the listener.

Step-by-Step Guide — [firefox] webRequest API

1. Initialize extension skeleton: create manifest.json and a background script (or service worker) and confirm you can load the extension temporarily in about:debugging.
2. Add permissions: add "permissions": ["webRequest", "webRequestBlocking"] and the host patterns you need (or <all_urls> for broad coverage). This enables the webRequest API for your extension.
3. Register listeners: in your background script use addListener for the events you need (onBeforeRequest, onBeforeSendHeaders, onHeadersReceived, etc.), providing a filter object (URL patterns, types) and extraInfoSpec (for example, "blocking", "requestHeaders", "responseHeaders", or "requestBody").
4. Implement handler logic: inspect the details object your listener receives and decide whether to allow, cancel, redirect, or modify headers. Keep blocking handlers fast and deterministic so you don”t delay the browser.
5. Test locally: load the extension via about:debugging, reproduce target requests in the browser, and use the extension”s console logs and the network panel to verify modifications or cancellations.
6. Harden and limit scope: replace broad host permissions with narrower patterns, remove unnecessary blocking privileges, and add error handling for edge cases like redirects and auth challenges.
7. Package and publish: once tested, increment version, sign/package according to Mozilla Add-ons guidelines, and submit the extension for review.

Use Cases & Examples

Ad or tracker blocking: register onBeforeRequest with URL filters for known ad domains and return {cancel: true} for matching requests to block network calls before they start.

Header injection for telemetry or auth: use onBeforeSendHeaders with extraInfoSpec that requests requestHeaders and return a modified header list to add an Authorization or custom-tracking header for selected hosts.

Conditional redirects: detect a request to a slow asset and return a redirect response to a cached CDN URL or local resource to improve performance for certain paths.

Common Issues

• Listener not fired: ensure host permissions match the request URL and that the event name is spelled correctly; confirm the background script is running.
• Modifications ignored: include webRequestBlocking in manifest and add "blocking" to extraInfoSpec for that listener when you need to modify or cancel requests.
• Extension causes slow page loads: minimize synchronous work in blocking listeners, avoid expensive I/O, and keep filters as narrow as possible to reduce the number of invocations.
• Missing headers in details: request the appropriate extraInfoSpec values (e.g., "requestHeaders" or "responseHeaders") and be aware some headers may be withheld by the browser for security reasons.

What”s Next

• Explore declarativeNetRequest (DNR) if you want rules-based blocking with lower runtime overhead.
• Combine webRequest with the proxy API for advanced routing or enterprise use cases.
• Use extension telemetry and logging to measure the performance impact of your handlers.

Related Resources

• Parent release guide: Release guide for Firefox 153
• Official documentation: MDN webRequest API

🛠️ Try These Free Tools

See all free tools →