network.beforeRequestSent event
The network.beforeRequestSent event of the network module fires before the browser sends a request over the network or before it handles the request using its cache or a service worker.
Event data
The params field in the event notification is an object with the following fields:
context-
A string that contains the ID of the context in which the request was made, or
nullif the request wasn't made by a document in a context, for example a request made by a worker. initiatorOptional-
An object that describes the JavaScript code that made the request. The browser includes it for a request made with
fetch()orXMLHttpRequest. It can contain the following fields:columnNumberOptional-
A non-negative integer that contains the zero-based column number of the code that made the request, or
0if the stack trace is empty. lineNumberOptional-
A non-negative integer that contains the zero-based line number of the code that made the request, or
0if the stack trace is empty. stackTraceOptional-
An object that represents the JavaScript stack at the point where the request was made. It contains the following field:
callFrames-
An array of zero or more stack-frame objects, ordered from the most recent call. Each object contains the following fields:
columnNumber-
A non-negative integer that contains the zero-based column number of the executed code.
functionName-
A string that contains the name of the executing function.
lineNumber-
A non-negative integer that contains the zero-based line number of the executed code.
url-
A string that contains the URL of the script.
interceptsOptional-
An array of one or more strings, each containing the ID of an intercept that blocks the request. This field is included only when
isBlockedistrue. Intercept IDs are returned by thenetwork.addInterceptcommand. isBlocked-
A boolean that indicates whether the request is blocked by an intercept.
true: The request matches one or more intercepts listed in theinterceptsfield and is blocked. The browser doesn't send the request until the client resumes it, for example with thenetwork.continueRequestcommand.false: The request doesn't match any of the session's intercepts, so the client doesn't need to resume it.
-
A string that contains the UUID that uniquely identifies the navigation that the request is part of, or
nullif the request isn't a navigation request. For example, the value isnullwhen requesting a document's subresources, such as stylesheets and scripts, or when making a request withfetch(). If the navigation was started using thebrowsingContext.navigateorbrowsingContext.reloadcommand, this ID matches thenavigationvalue in the command's response. Other events related to this navigation share the same navigation ID, including events in thebrowsingContextandnetworkmodules. redirectCount-
A non-negative integer that contains the number of redirects the browser has followed for this request. It is
0for the original request and increases by one with each redirect. request-
An object that describes the request. It contains the following fields:
bodySize-
A non-negative integer that contains the size of the request body in bytes, or
nullif the request has no body. -
An array of objects, each representing a cookie sent with the request. The array is empty if the request has no
Cookieheader. Each object contains the following fields and may additionally include browser-specific fields:domain-
A string that contains the domain of the cookie.
expiryOptional-
A non-negative integer that contains the expiry time of the cookie, as seconds elapsed since the epoch. This field is omitted for a cookie that has no expiry time, such as a session cookie.
httpOnly-
A boolean that indicates whether the cookie is hidden from page scripts by its
HttpOnlyattribute (true) or is accessible to them (false). name-
A string that contains the name of the cookie.
path-
A string that contains the path of the cookie.
sameSite-
A string that indicates the cookie's
SameSitesetting. It has one of the following values:default: The cookie has noSameSiteattribute or has an unrecognized value, so the browser's default behavior applies.lax: The cookie hasSameSite=Lax.none: The cookie hasSameSite=None.strict: The cookie hasSameSite=Strict.
secure-
A boolean that indicates whether the cookie is restricted to secure connections by its
Secureattribute (true) or can be sent over insecure connections (false). size-
A non-negative integer that contains the combined size of the cookie's name and value, in bytes.
value-
An object that contains the value of the cookie. It contains the following fields:
destination-
A string that contains the destination of the request, such as
document,script, orstyle. The string is empty for requests made withfetch()orXMLHttpRequest. headers-
An array of objects, each representing a header of the request, including headers added with the
network.setExtraHeaderscommand. Each object contains the following fields:name-
A string that contains the header name, such as
Accept. value-
An object that contains the header value. It contains the following fields:
headersSize-
A non-negative integer that contains the size of the request headers in bytes. For protocols that compress headers, such as HTTP/2, it represents the compressed size.
initiatorType-
A string that indicates what started the request, such as
fetch,link, orscript. For a request with no initiator type, such as the request for a page loaded into a tab, the value isnullinstead of a string. SeePerformanceResourceTiming.initiatorTypefor descriptions of common values. method-
A string that contains the HTTP request method, such as
GETorPOST. request-
A string that contains the ID of the request. The ID stays the same even when the request is redirected.
timings-
An object that contains the times at which the stages of the request happened. The
timeOriginfield contains a time in milliseconds since the epoch. The other fields in this object contain times in milliseconds relative totimeOrigin. A field is0if its stage hasn't happened, for example the redirect fields for a request that wasn't redirected. All the fields are0if the request wasn't made by a document or a worker. It contains the following fields:connectEnd-
A number that represents the time when the browser finished establishing the connection to the server, similar to
PerformanceResourceTiming.connectEnd. connectStart-
A number that represents the time when the browser started establishing the connection to the server, similar to
PerformanceResourceTiming.connectStart. dnsEnd-
A number that represents the time when the browser finished the domain name lookup, similar to
PerformanceResourceTiming.domainLookupEnd. dnsStart-
A number that represents the time when the browser started the domain name lookup, similar to
PerformanceResourceTiming.domainLookupStart. fetchStart-
A number that represents the time when the browser started fetching the resource after any redirects, similar to
PerformanceResourceTiming.fetchStart. redirectEnd-
A number that represents the time when the browser received the last byte of the response to the last redirect, similar to
PerformanceResourceTiming.redirectEnd. redirectStart-
A number that represents the time when the request that was redirected first started, similar to
PerformanceResourceTiming.redirectStart. requestStart-
A number that represents the time when the browser started sending the request, similar to
PerformanceResourceTiming.requestStart. requestTime-
A number that represents the time when the request started, similar to
PerformanceEntry.startTime. responseEnd-
A number that represents the time when the browser received the last byte of the response, similar to
PerformanceResourceTiming.responseEnd. responseStart-
A number that represents the time when the browser received the first byte of the response, similar to
PerformanceResourceTiming.responseStart. timeOrigin-
A number that represents the time origin of the document or worker that made the request.
tlsStart-
A number that represents the time when the browser started the TLS handshake to secure the connection, similar to
PerformanceResourceTiming.secureConnectionStart.
url-
A string that contains the URL of the request.
timestamp-
A non-negative integer that represents the time when the event was fired, as milliseconds elapsed since the epoch.
userContextOptional-
A string that contains the ID of the user context in which the request was made, or
nullif the request wasn't made by a document in a context.
Description
In the lifecycle of a request, this is the first event.
It is followed by the network.responseStarted event when the browser receives the response headers.
The network.responseCompleted event fires after the browser receives the whole response.
If the request fails at any point, network.fetchError fires as the last event for the request.
If you're subscribed to this event, you always receive it before any other event for the same request, even when the request fails before it is sent.
The event fires again for each redirect.
The request ID stays the same and redirectCount increases by one.
When isBlocked is true, the request waits until the client resumes it with the network.continueRequest, network.failRequest, or network.provideResponse command.
Examples
>Matching requests to a navigation
Assume you have a WebDriver BiDi connection, an active session, and a subscription to network.beforeRequestSent.
Suppose you use browsingContext.navigate to load https://example.com/ in a tab.
The page loads a stylesheet and a script.
The browser already has a theme=dark cookie for the site from an earlier visit.
The command, sent with wait set to complete, returns the navigation ID, but its response arrives after the event for the page request.
Before requesting the page, the browser sends the following event with the same navigation ID (for brevity, the headers array has been shortened and some fields in the request object have been omitted):
{
"type": "event",
"method": "network.beforeRequestSent",
"params": {
"context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
"isBlocked": false,
"navigation": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
"redirectCount": 0,
"request": {
"cookies": [
{
"domain": "example.com",
"httpOnly": false,
"name": "theme",
"path": "/",
"sameSite": "lax",
"secure": false,
"size": 9,
"value": {
"type": "string",
"value": "dark"
}
}
],
"destination": "document",
"headers": [
{
"name": "Host",
"value": {
"type": "string",
"value": "example.com"
}
},
{
"name": "Accept",
"value": {
"type": "string",
"value": "text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8"
}
},
{
"name": "Cookie",
"value": {
"type": "string",
"value": "theme=dark"
}
},
{
"name": "Sec-Fetch-Dest",
"value": {
"type": "string",
"value": "document"
}
}
],
"initiatorType": null,
"method": "GET",
"request": "b9e201af-6475-4bea-a174-51a8290f8087",
"url": "https://example.com/"
},
"timestamp": 1791903609108,
"userContext": "default"
}
}
Next, the browser sends an event for each subresource the page loads, such as its stylesheet. These requests have no navigation ID (only some of the fields are shown):
{
"type": "event",
"method": "network.beforeRequestSent",
"params": {
"context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
"isBlocked": false,
"navigation": null,
"redirectCount": 0,
"request": {
"destination": "style",
"initiatorType": "link",
"method": "GET",
"request": "37cf22b4-f399-4450-828d-d54fce56004e",
"url": "https://example.com/style.css"
},
"timestamp": 1791903609130
}
}
To match the events to the navigation, keep them until the command's response arrives, then compare their navigation field with the ID in the response.
Only the page request has a matching ID.
Requests for its subresources have a navigation value of null.
Receiving an event for a request made by a script
Using the same connection, session, and subscription as in the first example, suppose the page's script, /app.js, has a function that adds an item to a list with fetch():
function addItem(name) {
return fetch("/api/items", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({ name }),
}).then((response) => response.json());
}
When the page calls addItem("Pen"), the browser sends the following event before sending the request (only some of the fields are shown):
{
"type": "event",
"method": "network.beforeRequestSent",
"params": {
"context": "93ee5bd6-d256-4608-a002-9a8995cc0e5f",
"initiator": {
"columnNumber": 9,
"lineNumber": 1,
"stackTrace": {
"callFrames": [
{
"columnNumber": 9,
"functionName": "addItem",
"lineNumber": 1,
"url": "https://example.com/app.js"
}
]
}
},
"isBlocked": false,
"navigation": null,
"redirectCount": 0,
"request": {
"bodySize": 14,
"destination": "",
"initiatorType": "fetch",
"method": "POST",
"request": "ef49027d-aa97-44e4-bbe6-6ff8dbaa0c97",
"url": "https://example.com/api/items"
},
"timestamp": 1791903609159
}
}
The initiator points to the fetch() call in addItem() on line 1 and column 9 of /app.js, counting from zero.
In the request object, the initiatorType of fetch and the empty destination indicate that a script made the request.
The bodySize field contains the byte size of the JSON body, {"name":"Pen"}.
Keep the request ID to match this request with the events that follow, such as network.responseCompleted.
Specifications
| Specification |
|---|
| WebDriver BiDi> # event-network-beforeSendRequest> |
Browser compatibility
See also
network.responseStartedeventnetwork.responseCompletedeventnetwork.fetchErroreventnetwork.authRequiredeventbrowsingContext.navigationStartedeventsession.subscribecommand