Ingestion API

Header Hawk CSP Ingestion API v1.0.0

Scroll down for code samples, example requests and responses. Select a language for code samples from the tabs above or the mobile navigation menu.

API for receiving CSP (Content Security Policy) violation reports from browsers. Supports both CSP Level 2 format (report-uri) and Reporting API format (report-to).

Authentication

This API does not use traditional authentication. Instead, each site is assigned an 8-character ingestCode that is embedded in the URL path. This design is necessary because browsers cannot add custom headers to CSP report requests.

The ingestCode is:

Generated when a site is created
8 characters, base62 (a-z, A-Z, 0-9)
Validated via edge cache for fast rejection of invalid codes
Can be regenerated if compromised

Example CSP header configuration:

Content-Security-Policy: default-src 'self'; report-uri https://ingest.headerhawk.com/csp/Xk9mP2nQ

Base URLs:

Web: Header Hawk

Ingestion

submitCspReport

Code samples

const inputBody = '{
  "csp-report": {
    "document-uri": "http://example.com",
    "referrer": "string",
    "violated-directive": "string",
    "effective-directive": "string",
    "original-policy": "string",
    "disposition": "enforce",
    "blocked-uri": "string",
    "status-code": 0,
    "source-file": "string",
    "line-number": 0,
    "column-number": 0,
    "script-sample": "string"
  }
}';
const headers = {
  'Content-Type':'application/csp-report',
  'Accept':'application/json'
};

fetch('https://ingest.headerhawk.com/csp/{ingestCode}',
{
  method: 'POST',
  body: inputBody,
  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Content-Type': 'application/csp-report',
  'Accept': 'application/json'
}

r = requests.post('https://ingest.headerhawk.com/csp/{ingestCode}', headers = headers)

print(r.json())

# You can also use wget
curl -X POST https://ingest.headerhawk.com/csp/{ingestCode} \
  -H 'Content-Type: application/csp-report' \
  -H 'Accept: application/json'

POST /csp/{ingestCode}

Submit CSP violation report

Receives CSP violation reports from browsers. This endpoint URL is configured in the customer’s CSP header via report-uri or report-to directives.

The endpoint accepts both:

CSP Level 2 format (Content-Type: application/csp-report)
Reporting API format (Content-Type: application/reports+json)

Site identification is via the ingestCode path parameter. Invalid codes are rejected at the edge without database lookup.

Body parameter

{
  "csp-report": {
    "document-uri": "http://example.com",
    "referrer": "string",
    "violated-directive": "string",
    "effective-directive": "string",
    "original-policy": "string",
    "disposition": "enforce",
    "blocked-uri": "string",
    "status-code": 0,
    "source-file": "string",
    "line-number": 0,
    "column-number": 0,
    "script-sample": "string"
  }
}

Parameters

Name	In	Type	Required	Description
ingestCode	path	string	true	8-character site identifier. This code is provided when creating a site
body	body	CspReportPayload	true	none

Detailed descriptions

ingestCode: 8-character site identifier. This code is provided when creating a site and should be kept confidential to prevent unauthorized report submission.

Example responses

202 Response

{
  "status": "accepted",
  "reportId": "string"
}

400 Response

{
  "error": "invalid_format",
  "message": "Unable to parse CSP report"
}

404 Response

{
  "error": "not_found",
  "message": "Site not found"
}

410 Response

{
  "error": "gone",
  "message": "Site is no longer active"
}

429 Response

{
  "error": "rate_limited",
  "message": "Too many requests"
}

Responses

Status	Meaning	Description	Schema
202	Accepted	Report accepted for processing	Inline
400	Bad Request	Invalid report format	Error
404	Not Found	Invalid ingestCode or site not found	Error
410	Gone	Site is deactivated	Error
429	Too Many Requests	Rate limit exceeded	Error

Response Schema

Status Code 202

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» reportId	string	false	none	Unique ID assigned to this report (or batch)

Enumerated Values

Property	Value
status	accepted

Response Headers

Status	Header	Type	Format	Description
429	Retry-After	integer		Seconds until rate limit resets

Operations

healthCheck

Code samples

const headers = {
  'Accept':'application/json'
};

fetch('https://ingest.headerhawk.com/health',
{
  method: 'GET',

  headers: headers
})
.then(function(res) {
    return res.json();
}).then(function(body) {
    console.log(body);
});

import requests
headers = {
  'Accept': 'application/json'
}

r = requests.get('https://ingest.headerhawk.com/health', headers = headers)

print(r.json())

# You can also use wget
curl -X GET https://ingest.headerhawk.com/health \
  -H 'Accept: application/json'

GET /health

Health check endpoint

Example responses

200 Response

{
  "status": "healthy",
  "timestamp": "2019-08-24T14:15:22Z"
}

Responses

Status	Meaning	Description	Schema
200	OK	Service is healthy	Inline

Response Schema

Status Code 200

Name	Type	Required	Restrictions	Description
» status	string	false	none	none
» timestamp	string(date-time)	false	none	none

Enumerated Values

Property	Value
status	healthy

Schemas

CspReportPayload

{
  "csp-report": {
    "document-uri": "http://example.com",
    "referrer": "string",
    "violated-directive": "string",
    "effective-directive": "string",
    "original-policy": "string",
    "disposition": "enforce",
    "blocked-uri": "string",
    "status-code": 0,
    "source-file": "string",
    "line-number": 0,
    "column-number": 0,
    "script-sample": "string"
  }
}

CSP Level 2 report format (sent with report-uri directive)

Properties

Name	Type	Required	Restrictions	Description
csp-report	object	false	none	none
» document-uri	string(uri)	true	none	none
» referrer	string	false	none	none
» violated-directive	string	true	none	none
» effective-directive	string	false	none	none
» original-policy	string	true	none	none
» disposition	string	false	none	none
» blocked-uri	string	false	none	none
» status-code	integer	false	none	none
» source-file	string	false	none	none
» line-number	integer	false	none	none
» column-number	integer	false	none	none
» script-sample	string	false	none	none

Enumerated Values

Property	Value
disposition	enforce
disposition	report

ReportingApiPayload

{
  "age": 0,
  "body": {
    "blockedURL": "string",
    "disposition": "enforce",
    "documentURL": "http://example.com",
    "effectiveDirective": "string",
    "lineNumber": 0,
    "columnNumber": 0,
    "originalPolicy": "string",
    "referrer": "string",
    "sample": "string",
    "sourceFile": "string",
    "statusCode": 0
  },
  "type": "csp-violation",
  "url": "http://example.com",
  "user_agent": "string"
}

Reporting API format (sent with report-to directive)

Properties

Name	Type	Required	Restrictions	Description
age	integer	false	none	Milliseconds between violation and report
body	object	true	none	none
» blockedURL	string	false	none	none
» disposition	string	false	none	none
» documentURL	string(uri)	true	none	none
» effectiveDirective	string	true	none	none
» lineNumber	integer	false	none	none
» columnNumber	integer	false	none	none
» originalPolicy	string	true	none	none
» referrer	string	false	none	none
» sample	string	false	none	none
» sourceFile	string	false	none	none
» statusCode	integer	false	none	none
type	string	true	none	none
url	string(uri)	false	none	none
user_agent	string	false	none	none

Enumerated Values

Property	Value
disposition	enforce
disposition	report
type	csp-violation

Error

{
  "error": "string",
  "message": "string",
  "details": {}
}

Properties

Name	Type	Required	Restrictions	Description
error	string	true	none	Error code
message	string	true	none	Human-readable error message
details	object	false	none	Additional error context