The monitoring API lets you subscribe to changes on specific companies or persons. When the entity is updated in the official register, OpenRegister delivers a webhook notification to your configured endpoint — no polling required.
API monitors are completely separate from the Watchlist feature in the OpenRegister platform. They are independent systems and do not share state. Monitors created via the API only deliver webhooks to your configured endpoint; they do not appear in the platform Watchlist, and entries in your platform Watchlist do not trigger API webhooks.
Call POST /v1/monitor with the entity you want to watch, its type, and the data categories (preferences) you care about. The monitor stays active and delivers notifications until you explicitly delete it.
OpenRegister uses Svix to deliver webhook notifications. Svix is a reliable webhook infrastructure service that handles signing, retries, and delivery guarantees on your behalf. For a full overview of consuming Svix-powered webhooks, see the Svix receiving introduction.
OpenRegister sends a POST request to your configured endpoint with a JSON body.
Your endpoint must respond with a 2xx status code within 15 seconds. If it does not, Svix treats the delivery as failed and retries automatically with exponential back-off.
Disable CSRF protection for your webhook route — the requests come from Svix servers, not a browser, so CSRF tokens are never present.
Verifying the signature on each incoming webhook is important for two reasons:
Authenticity — confirms the request genuinely came from OpenRegister and not an attacker who found your endpoint URL.
Replay protection — Svix embeds a timestamp in every signature and the official libraries automatically reject messages with a timestamp more than five minutes old, preventing replay attacks.
Install the Svix library for your language and call the verify method on the webhook instance. Find your signing secret in your OpenRegister dashboard under the webhook endpoint you created.
Always pass the raw (unparsed) request body to verify. If your framework parses the JSON and you pass a re-serialised string, the cryptographic signature will not match and verification will fail.
import { Webhook } from "svix";const secret = process.env.WEBHOOK_SECRET!; // whsec_...export async function POST(req: Request) { const svixId = req.headers.get("svix-id") ?? ""; const svixTimestamp = req.headers.get("svix-timestamp") ?? ""; const svixSignature = req.headers.get("svix-signature") ?? ""; const body = await req.text(); // raw body — do not parse first const wh = new Webhook(secret); let event; try { event = wh.verify(body, { "svix-id": svixId, "svix-timestamp": svixTimestamp, "svix-signature": svixSignature, }); } catch { return new Response("Bad Request", { status: 400 }); } // Process event... return new Response("OK", { status: 200 });}
Svix Play is a free, no-signup webhook debugger. Use it during development to inspect incoming payloads before you have a publicly reachable endpoint.To get started:
Go to play.svix.com — you’ll receive a unique URL instantly.
Trigger an event (e.g. create a monitor and wait for an update, or replay a test event). Every delivery appears in the Svix Play UI with full headers, body, and response details.
For end-to-end local testing, install the Svix CLI and run:
svix listen http://localhost:8080/webhook
The CLI prints a public play.svix.com URL. Paste it into your dashboard as the endpoint and all deliveries are forwarded to your local server in real time.
Append the force_status_code query parameter to your Svix Play URL to make it return a specific error code. This lets you verify that OpenRegister’s retry logic works end-to-end:
How often OpenRegister checks an entity for changes depends on the entity type:Companies — checked for changes at least once per week.Persons — all entities are fully checked at least once per month. When a person incorporates a new company, that change is detected daily.Need faster updates? Contact us to discuss custom frequencies.
Preferences control which data categories trigger a notification. You must specify at least one preference when creating a monitor, and all preferences must match the entity_type.
Board or management roles the person holds across any company
holdings
Companies in which this person holds a stake
Passing a preference that does not apply to the given entity_type returns a 400 Bad Request validation error. For example, you cannot use representation when monitoring a person.
Compliance & KYC refresh — Monitor the companies and persons in your portfolio. When a director change, ownership update, or new financial filing is detected you receive an immediate notification, letting you trigger a re-verification workflow without scheduling periodic re-checks.Portfolio monitoring — Subscribe to basic and representation changes across all portfolio companies to track legal form conversions, address moves, insolvency filings, or management changes as they appear in the register.Ownership chain alerting — Combine ownership and holdings preferences to detect restructuring events in complex ownership chains. Useful for banks, investors, and compliance teams that need to know when a beneficial ownership chain changes.Due diligence pipelines — Automatically re-fetch company data and refresh documents when you receive a documents or financials notification, ensuring your internal records stay in sync with the official register.
Each monitor item in the list response includes a disabled boolean. A monitor is disabled when your account is downgraded to a plan that no longer includes monitoring access. Disabled monitors are preserved in your list so you do not lose your configuration, but they stop delivering notifications.Monitors are not automatically re-enabled on upgrade — this is intentional to prevent unexpected billing. To re-enable a disabled monitor, contact founders@openregister.de.
