Report-To
The HTTP Report-To response header defines endpoint groups where the browser sends reports such as CSP violations, network errors, and deprecation warnings.
Usage
The Report-To header tells the browser where to deliver reports generated by various reporting mechanisms. A server includes one or more JSON objects in the header value, each describing an endpoint group with a name, a lifetime, and one or more destination URLs.
Once the browser receives the Report-To
configuration, reports are sent out-of-band in the
background. This works with the
Content-Security-Policy
report-to directive,
Network Error Logging (NEL), and other
browser reporting features. The Report-To header is
part of an earlier iteration of the Reporting API
and is being replaced by the
Reporting-Endpoints
header in newer implementations.
Directives
group
The group directive is a string naming the
endpoint group. Other headers reference this name
to route reports to the correct destination. When
omitted, the group defaults to "default".
max_age
The max_age directive specifies the number of
seconds the browser keeps the reporting
configuration cached. After this time expires,
the browser discards the endpoint group and stops
sending reports to those URLs until a fresh
Report-To header is received. Setting
max_age to 0 removes a previously registered
group.
endpoints
The endpoints directive is an array of objects,
each containing a url property pointing to a
report collection endpoint. Multiple entries
provide failover: if the first URL is unreachable,
the browser tries the next one.
include_subdomains
The include_subdomains directive is a boolean.
When set to true, the reporting configuration
applies to all subdomains of the host serving the
header.
Example
The value is a JSON object. The group field gives
the endpoint group a name. The max_age field sets
how long the browser remembers this configuration,
in seconds. The endpoints array lists one or more
URLs where the browser sends reports. In this
example, the group is named cf-nel, the browser
caches the configuration for 7 days (604800
seconds), and network error reports are sent to
the specified URL.
Report-To: {"group":"cf-nel","max_age":604800,"endpoints":[{"url":"https://a.nel.example.re/report/v4"}]}
A video platform registers a reporting group for
CSP violations. The max_age of 2592000 sets a
30-day lifetime. The group name video-csp is
referenced by other headers to route specific
report types to this endpoint.
Report-To: {"group":"video-csp","max_age":2592000,"endpoints":[{"url":"https://csp.example.re/csp/report-to/video"}]}
The matching
Content-Security-Policy
header ties violation reports to the group by
referencing its name in the report-to directive.
Content-Security-Policy: default-src 'self'; report-to video-csp
Takeaway
The Report-To response header registers
browser-side endpoint groups for collecting CSP
violations, network errors, and other reports.
Newer implementations are moving toward the
Reporting-Endpoints header as a replacement.