---
title: webRequest
slug: Mozilla/Add-ons/WebExtensions/API/webRequest
tags:
  - API
  - Add-ons
  - Extensions
  - Interface
  - Non-standard
  - Reference
  - WebExtensions
translation_of: Mozilla/Add-ons/WebExtensions/API/webRequest
---
<div>{{AddonSidebar}}</div>

<p>Add event listeners for the various stages of making an HTTP request. The event listener receives detailed information about the request and can modify or cancel the request.</p>

<p>Each event is fired at a particular stage of the request. The typical sequence of events is like this:</p>

<p><img alt="" src="https://mdn.mozillademos.org/files/13376/webRequest-flow.png" style="display: block; height: 680px; margin-left: auto; margin-right: auto; width: 624px;"></p>

<p>{{WebExtAPIRef("webRequest.onErrorOccurred", "onErrorOccurred")}} can be fired at any time during the request. Also, note that sometimes the sequence of events may differ from this: for example, in Firefox, on an <a href="/en-US/docs/Web/HTTP/Headers/Strict-Transport-Security">HSTS</a> upgrade, the <code>onBeforeRedirect</code> event will be triggered immediately after <code>onBeforeRequest</code>.</p>

<p>All the events, except <code>onErrorOccurred</code>, can take three arguments to <code>addListener()</code>:</p>

<ul>
 <li>the listener itself</li>
 <li>a {{WebExtAPIRef("webRequest.RequestFilter", "filter")}} object, so you can only be notified for requests made to particular URLs or for particular types of resource</li>
 <li>an optional <code>extraInfoSpec</code> object. You can use this to pass additional event-specific instructions.</li>
</ul>

<p>리스너는 요청 정보가 담긴 <code>details</code> 객체를 받는다. This includes a request ID, which is provided to enable an add-on to correlate events associated with a single request. It is unique within a browser session and the add-on's context. It stays the same throughout a request, even across redirections and authentication exchanges.</p>

<p>webRequest API를 사용하려면 확장 프로그램은 "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API 권한</a>을 가져야 하고, 대상 호스트에 대해서도 <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">호스트 권한</a>을 가져야 한다. "blocking" 기능을  사용하려면 추가로 "webRequestBlocking" API 권한도 가져야 한다.</p>

<p>To intercept resources loaded by a page (such as images, scripts, or stylesheets), the extension must have the host permission for the resource as well as for the main page requesting the resource. For example, if a page at "https://developer.mozilla.org" loads an image from "https://mdn.mozillademos.org", then an extension must have both host permissions if it is to intercept the image request.</p>

<h2 id="Modifying_requests">Modifying requests</h2>

<p>On some of these events, you can modify the request. Specifically, you can:</p>

<ul>
 <li>cancel the request in:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li>
   <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</li>
   <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li>
  </ul>
 </li>
 <li>redirect the request in:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeRequest", "onBeforeRequest")}}</li>
   <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li>
  </ul>
 </li>
 <li>modify request headers in:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}
    <ul>
    </ul>
   </li>
  </ul>
 </li>
 <li>modify response headers in:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}}</li>
  </ul>
 </li>
 <li>supply authentication credentials in:
  <ul>
   <li>{{WebExtAPIRef("webRequest.onAuthRequired", "onAuthRequired")}}</li>
  </ul>
 </li>
</ul>

<p>To do this, you need to pass an option with the value "blocking" in the <code>extraInfoSpec</code> argument to the event's <code>addListener()</code>. This makes the listener synchronous. In the listener, you can then return a {{WebExtAPIRef("webRequest.BlockingResponse", "BlockingResponse")}} object, which indicates the modification you need to make: for example, the modified request header you want to send.</p>

<h2 id="Accessing_security_information">Accessing security information</h2>

<p>In the {{WebExtAPIRef("webRequest.onHeadersReceived", "onHeadersReceived")}} listener you can access the <a href="/en-US/docs/Glossary/TLS">TLS</a> properties of a request by calling {{WebExtAPIRef("webRequest.getSecurityInfo()", "getSecurityInfo()")}}. To do this you must also pass "blocking" in the <code>extraInfoSpec</code> argument to the event's <code>addListener()</code>.</p>

<p>You can read details of the TLS handshake, but can't modify them or override the browser's trust decisions.</p>

<h2 id="Modifying_responses">Modifying responses</h2>

<p>To modify the HTTP response bodies for a request, call {{WebExtAPIRef("webRequest.filterResponseData")}}, passing it the ID of the request. This returns a {{WebExtAPIRef("webRequest.StreamFilter")}} object that you can use to examine and modify the data as it is received by the browser.</p>

<p>To do this, you must have the "webRequestBlocking" API permission as well as the "webRequest" <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#API_permissions">API permission</a> and the <a href="/en-US/Add-ons/WebExtensions/manifest.json/permissions#Host_permissions">host permission </a>for the relevant host.</p>

<h2 id="Types">Types</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.BlockingResponse")}}</dt>
 <dd>
 <p>An object of this type is returned by event listeners that have set <code>"blocking"</code> in their <code>extraInfoSpec</code> argument. By setting particular properties in <code>BlockingResponse</code>, the listener can modify network requests.</p>
 </dd>
 <dt>{{WebExtAPIRef("webRequest.CertificateInfo")}}</dt>
 <dd>An object describing a single X.509 certificate.</dd>
 <dt>{{WebExtAPIRef("webRequest.HttpHeaders")}}</dt>
 <dd>An array of HTTP headers. Each header is represented as an object with two properties: <code>name</code> and either <code>value</code> or <code>binaryValue</code>.</dd>
 <dt>{{WebExtAPIRef("webRequest.RequestFilter")}}</dt>
 <dd>An object describing filters to apply to webRequest events.</dd>
 <dt>{{WebExtAPIRef("webRequest.ResourceType")}}</dt>
 <dd>Represents a particular kind of resource fetched in a web request.</dd>
 <dt>{{WebExtAPIRef("webRequest.SecurityInfo")}}</dt>
 <dd>An object describing the security properties of a particular web request.</dd>
 <dt>{{WebExtAPIRef("webRequest.StreamFilter")}}</dt>
 <dd>An object that can be used to monitor and modify HTTP responses while they are being received.</dd>
 <dt>{{WebExtAPIRef("webRequest.UploadData")}}</dt>
 <dd>Contains data uploaded in a URL request.</dd>
</dl>

<h2 id="Properties">Properties</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES", "webRequest.MAX_HANDLER_BEHAVIOR_CHANGED_CALLS_PER_10_MINUTES")}}</dt>
 <dd>The maximum number of times that <code><a href="https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/WebRequest/handlerBehaviorChanged" title="Suppose an add-on's job is to block web requests against a pattern, and the following scenario happens:"><code>handlerBehaviorChanged()</code></a></code> can be called in a 10 minute period.</dd>
</dl>

<h2 id="Methods">Methods</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.handlerBehaviorChanged()")}}</dt>
 <dd>This method can be used to ensure that event listeners are applied correctly when pages are in the browser's in-memory cache.</dd>
 <dt>{{WebExtAPIRef("webRequest.filterResponseData()")}}</dt>
 <dd>Returns a {{WebExtAPIRef("webRequest.StreamFilter")}} object for a given request.</dd>
 <dt>{{WebExtAPIRef("webRequest.getSecurityInfo()")}}</dt>
 <dd>Gets detailed information about the <a href="/en-US/docs/Glossary/TLS">TLS</a> connection associated with a given request.</dd>
</dl>

<h2 id="Events">Events</h2>

<dl>
 <dt>{{WebExtAPIRef("webRequest.onBeforeRequest")}}</dt>
 <dd>Fired when a request is about to be made, and before headers are available. This is a good place to listen if you want to cancel or redirect the request.</dd>
 <dt>{{WebExtAPIRef("webRequest.onBeforeSendHeaders")}}</dt>
 <dd>Fired before sending any HTTP data, but after HTTP headers are available. This is a good place to listen if you want to modify HTTP request headers.</dd>
 <dt>{{WebExtAPIRef("webRequest.onSendHeaders")}}</dt>
 <dd>Fired just before sending headers. If your add-on or some other add-on modified headers in <code>{{WebExtAPIRef("webRequest.onBeforeSendHeaders", "onBeforeSendHeaders")}}</code>, you'll see the modified version here.</dd>
 <dt>{{WebExtAPIRef("webRequest.onHeadersReceived")}}</dt>
 <dd>Fired when the HTTP response headers associated with a request have been received. You can use this event to modify HTTP response headers.</dd>
 <dt>{{WebExtAPIRef("webRequest.onAuthRequired")}}</dt>
 <dd>Fired when the server asks the client to provide authentication credentials. The listener can do nothing, cancel the request, or supply authentication credentials.</dd>
 <dt>{{WebExtAPIRef("webRequest.onResponseStarted")}}</dt>
 <dd>Fired when the first byte of the response body is received. For HTTP requests, this means that the status line and response headers are available.</dd>
 <dt>{{WebExtAPIRef("webRequest.onBeforeRedirect")}}</dt>
 <dd>Fired when a server-initiated redirect is about to occur.</dd>
 <dt>{{WebExtAPIRef("webRequest.onCompleted")}}</dt>
 <dd>Fired when a request is completed.</dd>
 <dt>{{WebExtAPIRef("webRequest.onErrorOccurred")}}</dt>
 <dd>Fired when an error occurs.</dd>
</dl>

<h2 id="Browser_compatibility">Browser compatibility</h2>



<p>{{Compat("webextensions.api.webRequest")}}</p>

<p> </p>

<p><a href="/docs/Mozilla/Add-ons/WebExtensions/Chrome_incompatibilities#webRequest_incompatibilities">Extra notes on Chrome incompatibilities</a>.</p>

<p> </p>

<p>{{WebExtExamples("h2")}}</p>

<div class="note"><strong>Acknowledgments</strong>

<p>This API is based on Chromium's <a href="https://developer.chrome.com/extensions/webRequest"><code>chrome.webRequest</code></a> API. This documentation is derived from <a href="https://chromium.googlesource.com/chromium/src/+/master/extensions/common/api/web_request.json"><code>web_request.json</code></a> in the Chromium code.</p>

<p>Microsoft Edge compatibility data is supplied by Microsoft Corporation and is included here under the Creative Commons Attribution 3.0 United States License.</p>
</div>

<div class="hidden">
<pre>// Copyright 2015 The Chromium Authors. All rights reserved.
//
// Redistribution and use in source and binary forms, with or without
// modification, are permitted provided that the following conditions are
// met:
//
//    * Redistributions of source code must retain the above copyright
// notice, this list of conditions and the following disclaimer.
//    * Redistributions in binary form must reproduce the above
// copyright notice, this list of conditions and the following disclaimer
// in the documentation and/or other materials provided with the
// distribution.
//    * Neither the name of Google Inc. nor the names of its
// contributors may be used to endorse or promote products derived from
// this software without specific prior written permission.
//
// THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
// "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
// LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
// A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
// OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
// SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
// LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
// DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
// THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
// (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
// OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
</pre>
</div>