Skip to content

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:

  1. 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-src or form-action, seen across enough browsers to be real, sent once. Sent instead of New CSP issue for that issue Every plan
    New framed origin Your policy refused a page’s attempt to load another origin in a frame, under frame-src or child-src, seen across enough browsers to be real, sent once. Sent instead of New CSP issue for that issue Every plan
    CSP policy changed A site’s reports carry a Content-Security-Policy it has not used recently Every 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.

  2. 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).

  3. 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.

  4. 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.

Type What you set
Email 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 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.

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.

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.

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.

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.

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.

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.

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.

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.

Working through it in order:

  1. 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.
  2. 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.
  3. The rule is disabled. It says why if something other than a person switched it off.
  4. 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.
  5. 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.
  6. 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.
  7. 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.
  8. 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.
  9. No reports are arriving at all. See Troubleshooting — an ad blocker or a domain mismatch will produce an empty dashboard rather than an error.

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.

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": "…"
}
{
"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"
}
}
  • disposition is enforce for Content-Security-Policy and report for Content-Security-Policy-Report-Only.
  • text is the policy in its normalised form: directives and sources sorted, nonces replaced by 'nonce-*'. It is cut at 16,384 characters, and truncated says when it was. hash identifies the whole policy either way.
  • previous is the last policy of the same disposition the site reported, or null when HeaderHawk remembers none.
  • first_seen is when the new policy was first reported, and report_count how many reports carried it when the alert was raised.
  • page_url is a page it was reported from, never with a query string.
{
"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"
}
]
}
  • header is the watched header’s name in lower case.
  • change is added, removed or changed. before is null for an added header, and after for 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.
{
"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.

{
"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.

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_page carries script, hash and sightings, and held_back: null. When a site has raised five script alerts in the hour, the next one is a summary instead: script, hash and sightings are null, and held_back gives hour_start, limit, and the event_type and script of the alert it stands in for.
  • script.changed carries script, the new hash, the pinned_hashes the script is authorized with, and sightings.
  • script.rejected_seen carries script, rejected_at, the rejection’s justification, last_seen and sightings, counted since the rejection.
  • script.gone carries script, the page (as a scan alert names it), status (unreviewed or authorized: a rejected script’s absence never alerts), last_seen (the last scan that found it), missing_since (the first that did not), scans_missing and baseline_scans.
  • script.origin_changed carries script (the URL that appeared; its script_id is "" and hash null when the scan could not fetch it), hash, previous (the URL that left, with its last_seen), origin, previous_origin, matched_on (the file name both share, build hashes as *), the page and sightings.
  • script.vulnerable carries library, version, the advisories new to you (each with id, aliases, summary, severity — critical or high — fixed_version, null when none is published, and url), the site’s scripts running the version (at most ten) and script_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.

{
"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.violation carries blocked_url and page_url, both without their query, and received_at.
  • reliability.spike carries kind (network or crash), recent_count, baseline_per_15_minutes, the window it counted (start, end), sampled (whether the counts are estimates) and top: up to three of the commonest network error types or crash reasons, as { "label", "count" }.
{
"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.

{
"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.

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.