How Alerting Works
Alerting is set up once for your whole organization, on Alerts. The page has three tabs. It opens on Rules until you have rules and something has been sent, and on History after that:
- Rules say what you are told about, on which sites, where it is sent and how soon. Each rule shows the events it covers, then one line of the rest that you can check at a glance: All sites → Organization admins · Immediately, once a day per issue.
- Destinations are where alerts can go: email, a Slack channel or a webhook. Each is set up once and can be used by any number of rules.
- History lists what was sent to each destination, and whether it arrived.
A new organization starts with an Organization admins email destination and two rules covering all sites and any event: one sends immediately, the other in a daily digest. You do not need to set anything up for alerts to reach your admins. “Any event” means every event your plan offers that the rule’s delivery supports, including events added later and events an upgrade makes available, so these rules keep up without you. A rule that names its events instead covers only those.
A rule has four parts, in the order the editor reads them back as a sentence:
-
When: the events it covers. The list comes from your plan:
Event What it means Plans New CSP issue A violation seen across enough browsers to be real, sent once (see below) Every plan New data destination Your policy refused a page’s attempt to send data to a host, under connect-srcorform-action, seen across enough browsers to be real, sent once. Sent instead of New CSP issue for that issueEvery plan New framed origin Your policy refused a page’s attempt to load another origin in a frame, under frame-srcorchild-src, seen across enough browsers to be real, sent once. Sent instead of New CSP issue for that issueEvery plan CSP policy changed A site’s reports carry a Content-Security-Policyit has not used recentlyEvery plan Security header changed A daily scan found a watched header added, removed or changed Professional and above Scan grade dropped A monitored page’s scan grade fell since its last scan Professional and above Page scan failing A monitored page could not be scanned three times in a row Professional and above New script on a payment page A script your site has never reported before runs on a payment page Professional and above Pinned script changed A script you authorized with pinned hashes runs with a hash nobody pinned Professional and above Rejected script seen again A script you rejected runs on a payment page after the rejection Professional and above New security policy issue An integrity, COEP, COOP, permissions or document policy issue seen across enough browsers, sent once Every plan Integrity check blocked a resource A browser refused a file that failed its integrity check, the first time for that URL in 7 days Every plan Network errors or crashes spiked A site’s network errors or crashes in 15 minutes passed 20 and five times their usual rate Every plan Deprecated feature due for removal A deprecated browser feature your pages still use is due to be removed within 60 days Every plan The policy, header and scan types are explained in Header Monitoring, the script types in Script Integrity Monitoring. Every type but the script types, integrity checks and spikes can be sent immediately or in a digest; those are sent immediately only, and a deprecation due for removal is listed in a digest only (see Browser report alerts). The script types are about payment pages whatever a rule’s page scope says: a new script seen only elsewhere is listed in the inventory and alerts nobody.
-
On: all sites, including new ones, or only the sites you pick. A rule on all sites covers a site you add next month without being edited. On the Professional plan and above, On payment pages only narrows an immediate rule to the pages you have marked as payment pages (Payment Pages).
-
Send: immediately, or in a daily or weekly digest. A new issue is sent immediately once, when it first reaches high confidence; while it continues it is in your digests, and it is sent again only if it comes back after being marked fixed, or someone reopens it (see Expected and fixed issues). For the other types, an immediate rule sends at most once in the period you choose about the same thing: the same policy, the same headers ending in the same values, the same drop between two grades, or the same page failing.
-
To: one or more destinations. Owners and admins can create a new one from inside the rule editor.
The editor shows the rule as a sentence as you fill it in: New CSP issue on all sites → Organization admins, immediately, at most once per issue every day. The Rules tab shows the same rule as its events and one line.
A rule can be switched off without deleting it. Something else can switch it off too, and the rule then says why:
- Every destination it sent to was deleted. Deleting a destination warns you first, naming the rules that would be left with nowhere to send.
- Every site it covered was deleted. Only a rule on selected sites can end up here.
- Your plan no longer includes one of its event types.
- Your plan no longer includes payment pages, for a rule scoped to them (see Payment Pages).
Nothing switches a rule back on by itself. Editing it and turning it on again does.
Destinations
Section titled “Destinations”| Type | What you set |
|---|---|
| People in your organization by role (for example “owners and admins”), and any other addresses | |
| Slack | A channel in the workspace connected on Settings → Integrations |
| Webhook | An HTTPS URL, and optionally a signing secret. With a secret, each request carries an HMAC-SHA256 X-HeaderHawk-Signature header |
A role recipient is worked out each time an alert is sent, so people who join or leave your organization are included or dropped without editing anything.
A webhook’s signing secret is stored encrypted and never shown again. Editing the destination shows it as Set, with Replace and Remove.
Test sends a clearly labelled notification through the same path a real alert takes, and shows the result on the destination: delivered, or rejected with the reason (for example the status your webhook answered with). The test is also recorded in History.
History
Section titled “History”History is the Alerts page’s third tab, and you can filter it by destination, site and event. Each row is one alert, digest or test sent to one destination, with its outcome. An alert’s row also says what it was about, in the alert’s own one-line summary: which script left which payment page, or both sides of a script’s move, marked as a pairing by file name. Alerts sent before that line was kept show only their type.
- Delivered: the email provider, Slack or your webhook accepted it.
- Rejected: it was refused, with the reason.
- Dropped: there was nothing to send it to, for example an email destination whose only address has not confirmed, or a Slack workspace that was disconnected.
Coverage on each site
Section titled “Coverage on each site”Settings → Sites shows, under each site, how many rules cover it and where they send. If no enabled rule covers a site, the Issues page says so while you look at that site, with a link that opens a new rule already scoped to it. It also says when a site’s new CSP issues are covered and its data destinations are not, or the other way round.
Policy, header and scan changes
Section titled “Policy, header and scan changes”These do not go through the windows and the confidence gate below. A policy change is raised once the new policy has been reported by two browser families or 20 times, and a scan result is raised when the scan that found it finishes. From there they follow the same rules, cooldowns, destinations and history as issues. A digest lists a site’s changes for the period alongside its issues, leaving out any already sent to the same destination immediately.
Each alert says what changed and from what, and links to the history it came from. None of them says whether the change was authorized: HeaderHawk cannot know, and whoever owns the site decides.
Data destinations
Section titled “Data destinations”A CSP issue in connect-src or form-action whose blocked source is a host
is a page trying to send data somewhere your policy does not allow. It alerts
as New data destination instead of New CSP issue, under the same
confidence gate and cooldown, so a rule can be about where your pages send
data and nothing else. The alert names the host and says whether a policy
discovery run had seen it before your policy refused it. When your policy is
report-only, it says the policy would have blocked the request, since in
report-only mode nothing is blocked.
A rule that covers any event hears about both. A rule that names New CSP
issue and not New data destination does not hear about refused
destinations, in real time or in its digest; the rule editor starts a new rule
with both. An img-src refusal stays a New CSP issue, because nearly every image a
page loads is only an image. Data smuggled out in an image URL is still
reported, and listed under img-src on the Issues page.
HeaderHawk sees where a page tried to send data, never what it sent. A
destination your policy already allows produces no report, so these alerts
are only as complete as your connect-src and form-action are tight.
Framed origins
Section titled “Framed origins”A CSP issue in frame-src (or child-src, its fallback) whose blocked source
is a host is a page trying to load another origin in a frame. On a checkout
that is usually where the card fields live, since payment providers host them
on their own origin inside your page. It alerts as New framed origin
instead of New CSP issue, the same way a refused data destination does,
and a new rule starts with it selected too. A rule that names New CSP
issue and not New framed origin does not hear about refused frames.
It alerts on every page, not only on payment pages, so a site with none
marked still learns that its pages framed somewhere new. When the frame was on
a payment page, the alert leads with it: the
subject starts Payment page: and the webhook’s on_payment_page is true.
A rule scoped to payment pages hears only those.
HeaderHawk sees which origin a page tried to frame, never what the frame
contains: a frame from another origin is closed to the page holding it, and no
browser report describes its contents. An origin your policy already allows
produces no report. frame-ancestors, which is about who frames your page
rather than what it frames, stays a New CSP issue. See
Framed Origins.
Script alerts
Section titled “Script alerts”These do not go through the windows and the confidence gate below either: only Chromium browsers report script hashes, so two browser families is a bar a script can never clear. A script alert waits instead until browsers on at least two different networks have reported it on a payment page, within a day of its first report, so a single forged report cannot raise one. A site raises at most five new or changed script alerts an hour; past that, one message says the rest of the hour’s are held back. A rejected script seen again always alerts. See Script Integrity Monitoring.
Script gone from a payment page (script.gone) and Script moved to
another origin (script.origin_changed) come from the daily scan of a
payment page alone, never from browsers going quiet, so they need no networks
either. A script is gone when the scan had found it in 3 scans in a row and has
not in the last 2; a move pairs a script that left with a file of the same name
that appeared from another origin, and is labelled a guess. A move is one alert,
in place of the new URL’s new-script alert. A gone script can also go to a
daily or weekly digest; a move is immediate only. See
Script Integrity Monitoring.
Script has a known vulnerability (script.vulnerable, Professional and
above) is different again: it is about a library version, not about payment
pages, so a rule limited to payment pages does not hear it. It fires once per
tenant, advisory and version, for high and critical advisories only, when a
script is first identified as an affected version or when the daily check
finds a newly published advisory. Unlike the payment-page script alerts it can
also go to a daily or weekly digest. See
Script Integrity Monitoring.
Browser report alerts
Section titled “Browser report alerts”Four event types come from the other report types a site can send (Report Types). All four are on every plan.
- New security policy issue follows the same windows and confidence gate as a new CSP issue, described below: an integrity, COEP, COOP, permissions or document policy issue alerts immediately once two browser families, or 20 signal reports, reported it within 15 minutes, and otherwise reaches you in a digest.
- Integrity check blocked a resource alerts on the first enforced integrity violation of a URL, then stays quiet about that URL for 7 days. A report-only violation never alerts: in report-only mode every script without integrity metadata reports, which is setup work rather than an attack.
- Network errors or crashes spiked is checked every 15 minutes. It alerts when a site’s network errors, or its crashes, in the last 15 minutes reached 20 and five times their average per 15 minutes over the past week. Counts are estimates when the reports are sampled.
- Deprecated feature due for removal is never sent immediately. Monday’s digest lists each deprecation your pages reported that week whose anticipated removal is within 60 days, whether the rule is daily or weekly.
Alerts from these types are about a whole site: a rule scoped to payment pages does not receive them.
Reports are grouped into issues, not alerted individually
Section titled “Reports are grouped into issues, not alerted individually”Every report is reduced to a signature: the combination of the violated directive and the blocked host. Reports sharing a signature are the same issue, however many pages they came from.
Alerting accumulates reports per signature in a 15-minute window. This matters more than it sounds: nine different violations produce nine separate windows of one report each, not one window of nine. Triggering a handful of distinct violations by hand to test alerting will not produce an alert, because no single signature reaches the threshold. Use a destination’s Test button instead.
The confidence gate
Section titled “The confidence gate”When a window closes, it is scored. Only high confidence windows are sent by an immediate rule.
| Confidence | Condition | Where it goes |
|---|---|---|
| High | Reported by 2 or more browser families, or 20+ signal reports | Immediate rules, and digests |
| Medium | 5–19 signal reports from a single browser family | Digests |
| Low | 1–4 signal reports from a single browser family | Digests |
| Suppressed | Every report classified as likely noise | Neither |
“Signal reports” excludes reports classified as noise. Known noise (browser
extension schemes, bot traffic, and about: URIs, or data: and blob: URIs
blocked by anything but a script directive) never enters a window at all, so an
extension that fires thousands of times cannot raise one. Likely noise, a
data: or blob: URI blocked as a script, is counted but is not signal, so a
window of 50 of those scores as suppressed, not high. Its issue stays on the
Issues page, marked Noise.
Browser diversity is the strongest signal available. A violation that Chrome, Firefox, and Safari all report is almost certainly real; one that a single browser reports a handful of times usually is not.
Expected and fixed issues
Section titled “Expected and fixed issues”An issue’s drawer on the Issues page starts with its decision. A member, admin or owner can mark it:
- Expected: the reports are real and are meant to stay, such as a vendor you will not allow or an extension the noise classifier missed. The issue leaves the default list and the Overview, is never sent as an alert, and is left out of digests. Its reports still count everywhere else.
- Fixed: you changed your policy or page. The issue leaves the default list, and reopens on its own when a report arrives after you marked it, which is the check you cannot make by hand. It is then new again: listed, counted on the Overview, and sent once more.
Either can be reopened, and every decision is kept with who made it, when and the note they left. The list shows open issues unless you choose Expected, Fixed or All states.
For a host a policy blocked, the drawer also shows the source that would allow it, as text to copy. Whether to add it is yours: if the resource should not load, mark the issue expected instead.
Why a rule might not have fired
Section titled “Why a rule might not have fired”Working through it in order:
- The issue is not high confidence. Open it and read the confidence reason — “1 signal report from 1 browser family” is the answer. It will be in the next digest instead.
- No enabled rule covers the site. The Issues page says so for the site you are looking at; Settings → Sites shows every site’s coverage. An issue that no rule covers when its window closes is not held for a rule you add later.
- The rule is disabled. It says why if something other than a person switched it off.
- The issue had already been sent. A new issue alerts once; while it continues it is in your digests. It alerts again when it comes back after being marked fixed, or when someone reopens it.
- The issue is marked expected or fixed. Its drawer says who marked it and when. A fixed issue alerts again on its first report after the fix.
- The alert was within the rule’s once-per-issue period. An earlier alert for the same issue on the same site is still inside it.
- The issue’s report type is in its first week on the site. For seven days after a security policy type is switched on, an immediate rule leaves its new issues to the digest, where a digest rule covers the site too (see Your Next Step). A blocked script from an enforced integrity policy is never held back.
- It was sent and not delivered. History shows each delivery’s outcome and the reason for a rejection. Use Test on the destination to check it.
- No reports are arriving at all. See Troubleshooting — an ad blocker or a domain mismatch will produce an empty dashboard rather than an error.
Webhook payloads
Section titled “Webhook payloads”A webhook destination receives a JSON POST. Its event field says which
payload it is:
event |
Sent for |
|---|---|
csp.issue.new |
New CSP issue |
data.new_destination |
New data destination |
frame.new_origin |
New framed origin |
csp.policy.changed |
CSP policy changed |
header.changed |
Security header changed |
scan.grade_dropped |
Scan grade dropped |
scan.failing |
Page scan failing |
script.new_on_payment_page |
New script on a payment page |
script.changed |
Pinned script changed |
script.rejected_seen |
Rejected script seen again |
script.gone |
Script gone from a payment page |
script.origin_changed |
Script moved to another origin |
script.vulnerable |
Script has a known vulnerability |
policy.new_issue |
New security policy issue |
integrity.violation |
Integrity check blocked a resource |
reliability.spike |
Network errors or crashes spiked |
csp.digest |
A daily or weekly digest |
headerhawk.test |
The Test button on a destination |
A receiver should ignore an event it does not recognise and fields it does
not use, so new types and fields can be added without breaking it. A Slack
incoming-webhook URL is sent a Slack message instead of these payloads.
Fields every change alert carries
Section titled “Fields every change alert carries”csp.policy.changed, header.changed, scan.grade_dropped,
scan.failing, the script events and the three browser report events share
these fields:
| Field | Meaning |
|---|---|
alert_id |
The alert’s id |
timestamp |
When this request was sent |
site_id |
The site |
site_name |
The site’s name |
summary |
One line saying what changed |
occurred_at |
When HeaderHawk observed the change |
rules |
Each rule that sent it here, as { "id", "name" } |
dashboard_url |
The site’s policy changes, the monitored page’s scan history under Headers, or the script on the Scripts page |
The three scan events also carry the page the scan was of:
"page": { "page_id": "…", "label": "Checkout", "scan_url": "https://shop.example.com/checkout", "scan_id": "…"}csp.policy.changed
Section titled “csp.policy.changed”{ "event": "csp.policy.changed", "alert_id": "…", "timestamp": "2026-09-17T09:00:00.000Z", "site_id": "…", "site_name": "Shop", "summary": "New Content-Security-Policy reported from shop.example.com", "occurred_at": "2026-09-17T08:59:58.000Z", "rules": [{ "id": "…", "name": "Policy changes" }], "dashboard_url": "https://app.headerhawk.com/dashboard/settings/sites/…/policies", "policy_change": { "policy": { "hash": "…", "disposition": "enforce", "text": "default-src 'self'; script-src 'nonce-*' 'self'", "truncated": false }, "previous": { "hash": "…", "disposition": "enforce", "text": "default-src 'self'; script-src 'self'", "truncated": false, "last_seen": "2026-09-17T08:41:12.000Z" }, "first_seen": "2026-09-17T08:52:03.000Z", "report_count": 3, "page_url": "https://shop.example.com/checkout" }}dispositionisenforceforContent-Security-PolicyandreportforContent-Security-Policy-Report-Only.textis the policy in its normalised form: directives and sources sorted, nonces replaced by'nonce-*'. It is cut at 16,384 characters, andtruncatedsays when it was.hashidentifies the whole policy either way.previousis the last policy of the same disposition the site reported, ornullwhen HeaderHawk remembers none.first_seenis when the new policy was first reported, andreport_counthow many reports carried it when the alert was raised.page_urlis a page it was reported from, never with a query string.
header.changed
Section titled “header.changed”{ "event": "header.changed", "…": "the shared fields and page above", "changes": [ { "header": "strict-transport-security", "change": "changed", "before": "max-age=31536000; includesubdomains", "after": "max-age=0" } ]}headeris the watched header’s name in lower case.changeisadded,removedorchanged.beforeisnullfor an added header, andafterfor a removed one.- Values are in the form scans compare: a policy normalised as above, any other header lower-cased with whitespace collapsed. A header sent more than once has each value on its own line.
scan.grade_dropped
Section titled “scan.grade_dropped”{ "event": "scan.grade_dropped", "…": "the shared fields and page above", "grade_drop": { "previous_grade": "A", "grade": "C", "algorithm_version": 3, "cap_reason": "`Strict-Transport-Security` is missing." }}Grades are A+, A, B, C, D or F. algorithm_version is the
rubric both grades came from; grades from different versions are never
compared. cap_reason is the one reason the grade is capped where it is, or
null.
scan.failing
Section titled “scan.failing”{ "event": "scan.failing", "…": "the shared fields and page above", "failure": { "consecutive_failures": 3, "reason": "timeout", "message": "shop.example.com did not answer within 10 seconds." }}reason is one of timeout, tls_failure, connection_failed,
too_many_redirects, bot_challenge, access_denied, server_error,
not_html or not_allowed (the page, or a redirect from it, led off the
site’s hosts or to an address scans do not connect to). message says the
same thing in a sentence.
Script alerts
Section titled “Script alerts”The three script events name the script (its URL without the query) and the reports behind the alert:
{ "event": "script.changed", "…": "the shared fields above", "script": { "script_id": "…", "url": "https://js.stripe.com/v3" }, "hash": "sha256-…", "pinned_hashes": ["sha256-…"], "sightings": { "source": "browser", "report_count": 4, "network_count": 2, "pages": [{ "page_id": "…", "label": "Checkout" }], "page_url": "https://shop.example.com/checkout/pay", "since": "2026-09-18T09:00:00.000Z" }}script.new_on_payment_pagecarriesscript,hashandsightings, andheld_back: null. When a site has raised five script alerts in the hour, the next one is a summary instead:script,hashandsightingsarenull, andheld_backgiveshour_start,limit, and theevent_typeandscriptof the alert it stands in for.script.changedcarriesscript, the newhash, thepinned_hashesthe script is authorized with, andsightings.script.rejected_seencarriesscript,rejected_at, the rejection’sjustification,last_seenandsightings, counted since the rejection.script.gonecarriesscript, thepage(as a scan alert names it),status(unreviewedorauthorized: a rejected script’s absence never alerts),last_seen(the last scan that found it),missing_since(the first that did not),scans_missingandbaseline_scans.script.origin_changedcarriesscript(the URL that appeared; itsscript_idis""andhashnull when the scan could not fetch it),hash,previous(the URL that left, with itslast_seen),origin,previous_origin,matched_on(the file name both share, build hashes as*), thepageandsightings.script.vulnerablecarrieslibrary,version, theadvisoriesnew to you (each withid,aliases,summary,severity—criticalorhigh—fixed_version, null when none is published, andurl), the site’sscriptsrunning the version (at most ten) andscript_count.
hash is "" for a script loaded cross-origin without CORS, which browsers
report without a hash. sightings.source says what raised the alert:
browser, when reports from two different networks did, and network_count
is how many networks reported it; or scan, when the daily scan of a payment
page fetched the script itself, and the counts are whatever browsers had
reported by then, often none.
Browser report alerts
Section titled “Browser report alerts”{ "event": "policy.new_issue", "…": "the shared fields above", "signature": "…", "report_type": "coep", "issue": { "description": "COEP: corp (cdn.example.net)", "subject": "corp", "target_host": "cdn.example.net", "document_host": "shop.example.com", "received_at": "2026-09-18T09:30:00.000Z" }}integrity.violationcarriesblocked_urlandpage_url, both without their query, andreceived_at.reliability.spikecarrieskind(networkorcrash),recent_count,baseline_per_15_minutes, thewindowit counted (start,end),sampled(whether the counts are estimates) andtop: up to three of the commonest network error types or crash reasons, as{ "label", "count" }.
Data destinations
Section titled “Data destinations”{ "event": "data.new_destination", "…": "the shared fields above", "signature": "…", "destination": { "host": "collect.example.net", "directive": "connect-src", "first_refused_at": "2026-09-18T09:20:00.000Z", "discovered_at": null }, "disposition": "enforce", "on_payment_page": true, "report": { "document_host": "shop.example.com", "received_at": "2026-09-18T09:30:00.000Z" }}discovered_at is when a policy discovery run first saw the host, and null
when none did. first_refused_at is the site’s first refusal of it, null
when HeaderHawk has no record to read (it could not be read, or the site
reached its 100 new hosts of that kind for the day), and then discovered_at says nothing
either. disposition is report when the refusing policy was
report-only, and null when the report did not say.
Framed origins
Section titled “Framed origins”{ "event": "frame.new_origin", "…": "the shared fields above", "signature": "…", "on_payment_page": true, "frame": { "host": "pay.example.net", "directive": "frame-src", "first_refused_at": "2026-09-18T09:20:00.000Z", "discovered_at": null }, "disposition": "enforce", "report": { "document_host": "shop.example.com", "received_at": "2026-09-18T09:30:00.000Z" }}The fields mean what they mean for a data destination, for the framed origin.
Changes in a digest
Section titled “Changes in a digest”Each site in a csp.digest payload has a changes list beside its issues:
the site’s policy, header and scan changes in the period, newest first,
leaving out any already sent to this destination immediately.
"changes": [ { "event_type": "header.changed", "summary": "Checkout: Strict-Transport-Security changed", "occurred_at": "2026-09-16T14:02:11.000Z", "page_id": "…" }]event_type is the event type’s own name (csp.policy_changed,
header.changed, scan.grade_dropped, scan.failing, or on Mondays
browser_change.removal_approaching), which for a policy change differs from
the immediate payload’s csp.policy.changed. page_id is null for a
policy change and a removal. Each issue carries report_type: csp-violation,
or the security policy type of a new security policy issue. A site can have changes and no issues, and a
receiver written before changes existed can ignore it.
A site whose security policy types are in their first week carries
first_week: one { "label", "since" } per stage of
the onboarding ladder that switched them on,
such as window, feature and document policies, with the time the first of
them went on. For seven days after such a type is switched on, an immediate
rule does not send its new issues as they arrive, so the digest is where they
are listed. A site in no first week has no first_week.