Helheim external canary success for GET /health and GET /v1/rates?jurisdiction=DE
API latency
p95 below 300 ms
Helheim external canary request duration from the EU vantage point
Data freshness
Within the published freshness window for each data type
GET /health?strict=1 (503 on any stale or entirely-absent collector region) plus /v1/status region health and meta.data_freshness on /v1/rates and /v1/thresholds
Webhook delivery
99% delivered within 6 hours
Durable webhook delivery records and retry outcomes
Freshness is measured from the last successful source verification timestamp.
Rate and threshold API responses include provenance and freshness metadata so
customers can inspect the source and verification time for returned data.
ShipVAT is probed from the Helheim cluster, outside Cloudflare Workers. The
canary runs every 60 seconds and checks:
GET https://api.shipvat.com/health
GET https://api.shipvat.com/v1/rates?jurisdiction=DE
Authorization:Bearer <dedicated canary API key>
The rates probe validates both HTTP success and the response contract: Germany
must return rate records plus public provenance and freshness metadata.
Canary metrics feed the ShipVAT Grafana SLO dashboard and Alertmanager burn
alerts. A failing Worker, dependency outage, broken route, invalid canary key,
or missing response metadata causes the canary to fail from the external vantage
point.
The plain GET /health above is a liveness probe only: by design (see the
public health response schema) it stays HTTP 200 even when a collector region
is stale or degraded, so it cannot page on a data freshness breach on its own.
GET /health?strict=1 is the dedicated freshness detection surface: it
returns the same body but responds 503 whenever any region in the expected
collector set (EU, UK, US, US-TAX, CA, AU, TAXABILITY) is stale
or entirely missing from sync metadata. This is what a freshness page/alert
should probe — not the plain /health route.
External owner action required (outside this repo): as of this fix,
nothing in Helheim’s canary/Alertmanager configuration probes
/health?strict=1 yet, so a data freshness breach still would not page.
The Helheim canary (k8s-gitops-helheim, owner-gated) needs an additional
probe added for:
GET https://api.shipvat.com/health?strict=1
alerting (PagerDuty, per the existing critical-alert routing below) on any
non-200 response. This document only covers the in-repo half (the route
exists and is documented here); wiring the external monitor is a separate,
named action for whoever owns the Helheim canary config.
SLO burn alerts are evaluated in Helheim Alertmanager. Critical alerts route to
PagerDuty; warning alerts route to Slack. ShipVAT also keeps independent Resend
email alerts for collector parse failures and digest emails as a fallback path.
The public status page is available at https://shipvat.com/status; the raw
collector status API is: