companydata.dk Webhooks API
Webhooks let your application receive real-time notifications when company data changes in the CVR registry. Useful for monitoring a portfolio of clients, prospects, suppliers, or any list of CVRs you care about. **Pro subscription required**, except `GET /v1/webhooks/event-types` which is open to any API key. Pro accounts can register up to **5 webhooks**, each monitoring up to **50,000 CVRs**. ## Authenticating to this API All `/v1/webhooks/*` requests authenticate the same way as the rest of the companydata.dk API: a Bearer token in the `Authorization` header. ``` Authorization: Bearer sk_live_your_api_key ``` ## Setup in three steps **1. Create an HTTPS endpoint** on your server that accepts `POST` with a JSON body. Return any `2xx` status code to acknowledge receipt. Anything outside `2xx` is treated as a failed delivery. **2. Register the webhook** with `POST /v1/webhooks`. The response includes a `secret` — **store it immediately**, it is only returned once and is required to verify incoming payloads. Until step 3 is completed, a freshly created webhook receives **no events**. **3. Tell us which CVRs to monitor** with `PUT /v1/webhooks/{webhook_id}/cvr-filter`. Send the full list of 8-digit CVR numbers you care about (up to 50,000 per webhook). Re-send the full list any time you want to change which companies are tracked. ## Payload Every event POSTs a JSON body matching the `WebhookPayload` schema to your URL: ```json { "event_id": "9c1f7e64-3b8a-4f0d-9a25-1d6c8a4e7f10", "event_type": "ownership", "cvr": "12345678", "company_name": "Example ApS", "changes": [ {"field": "ownership_percent", "old_value": "25.0", "new_value": "51.0"} ], "summary": { "da": "Ejerandel ændret fra 25% til 51%", "en": "Ownership percent changed from 25% to 51%" }, "detected_at": "2026-04-28T09:14:22Z", "timestamp": "2026-04-28T09:14:23Z" } ``` `event_id` is a UUIDv4, globally unique, and **stable across retries** — use it as the key for de-duplication. The `changes` array contains field-level diffs and may be empty for some event types; values are always strings (or `null`). The human-readable `summary` is always populated. Discover the full list of event types with `GET /v1/webhooks/event-types`. ## Delivery semantics - **Latency.** Most events are delivered within a few minutes of detection. Annual report (`financial`) events are batch-processed and may take **up to 24 hours** because XBRL parsing is queued. - **At-least-once.** Network errors and retries can cause the same event to be delivered more than once. De-duplicate on `event_id` (a 7-day cache window is more than sufficient). - **Ordering.** Events are not strictly ordered. Use `detected_at` to sequence changes for a given company on your side. - **No replay or backfill.** Events that exhaust their retry budget are not re-attempted. If your consumer is down longer than the retry window, reconcile by re-fetching the affected companies from `GET /v1/companies/{cvr}` once you're back up. ## Headers Every delivery includes: | Header | Description | |---|---| | `Content-Type` | Always `application/json` | | `X-Companydata-Signature` | `sha256=` — HMAC-SHA256 of the raw request body using your webhook secret | | `X-Companydata-Event` | The event type (matches `event_type` in the body) | | `X-Companydata-Delivery` | Unique delivery ID — changes on each retry. Useful for support | Any custom headers you set when creating the webhook are added to every delivery. ## Verifying the signature Compute HMAC-SHA256 of the raw request body using your webhook `secret` and compare it to the hex value after `sha256=` in `X-Companydata-Signature`. **Always use a constant-time comparison.** ```python import hmac, hashlib def verify(raw_body: bytes, signature_header: str, secret: str) -> bool: expected = "sha256=" + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature_header) ``` ```javascript import { createHmac, timingSafeEqual } from "crypto"; function verify(rawBody, signatureHeader, secret) { const expected = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"); return timingSafeEqual(Buffer.from(expected), Buffer.from(signatureHeader)); } ``` ## Retries and auto-disable - Each delivery is attempted **up to 3 times**. Anything outside `2xx` (including timeouts after 10s) is retried automatically. Retries are spaced roughly **2 minutes apart**, so a delivery either succeeds or is permanently failed within ~5 minutes of the first attempt. - Your endpoint should respond quickly — ideally enqueue the payload and return `200` immediately. - After **10 consecutive failures** across deliveries, the webhook is **auto-disabled** and `active` is set to `false`. Re-enable it with `PUT /v1/webhooks/{webhook_id}` and `{"active": true}` once the underlying issue is fixed; this also resets the failure counter. ## Inspecting deliveries `GET /v1/webhooks/{webhook_id}/deliveries` lists recent delivery attempts (HTTP status, truncated response body, error messages, timestamps) with `limit` and `offset` for pagination. `POST /v1/webhooks/{webhook_id}/test` sends a synthetic event to your URL — use this to verify your endpoint accepts the payload and signature before going live.