One watchlist per organisation, an event feed, and alerts by webhook or e-mail. The same keys as the other APIs, but its own product with its own plan: the price is per watched company per month, and watching never counts as a lookup.
Watch companies. Adds up to 10 000 organisasjonsnumre per call; the plan decides the total (409 watch_limit_exceeded). Unknown numbers are kept and flagged. Sole proprietorships and other entries that are, or may be, a person are kept, flagged natural_person, and never alerted or billed. Only events detected after a company is added are delivered, plus the last 30 days when include_last_30_days is true.
Change delivery settings. webhook_url must be https on port 443 or 8443 and resolve to public addresses only; an empty string removes it. email_mode is off, immediate or daily (07:00 Oslo). email_locale is nb or en.
Webhook signing secret: shown once, then metadata. The plaintext secret is returned by the first GET after the watchlist is created, and by every rotation; after that this returns only metadata (secret_hint, rotated_at, previous_secret_valid_until, secret_revealed). Lost it? POST rotates.
Rotate the webhook signing secret. Returns the new secret, once. The previous secret keeps signing for 24 hours: Datakilde-Signature then reads t=<unix>,v1=<new>,v1=<previous>, and a receiver accepts the request if either v1 matches. After the window the header has a single v1.
Alerts are sent as a POST with Content-Type: application/json to the URL in the settings. Any 2xx is a successful delivery. Delivery is at least once: deduplicate on id. Redirects are not followed, and the URL must be https on port 443 or 8443 and resolve to public addresses.
Headers
Header
Carries
Datakilde-Signature
t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>" with the watchlist's secret>
Datakilde-Timestamp
The same t as in the signature.
Datakilde-Event-Id
The payload's id. Delivery is at least once: deduplicate on it.
Retries
A non-2xx answer, a timeout or a refused connection is retried after 1, 2, 4, 8, 16, 32, 64, 128 minutes. After 9 attempts the delivery is dead; it is listed under /watchlist/deliveries?status=dead and can be requeued.
Compute the signature on the raw bytes, before parsing JSON, with the secret from /watchlist/webhook/secret. POST /watchlist/webhook/test sends a signed sample.
import hashlib, hmac, time
def verify(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
t, v1 = parts.get("t", ""), parts.get("v1", "")
if not t.isdigit() or abs(time.time() - int(t)) > tolerance:
return False
expected = hmac.new(secret.encode(), f"{t}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, v1)
Example payload
The body the test endpoint sends, generated from the code that sends it. test is true only there.