---
title: "/webhooks"
method: POST
path: "/v1/webhooks"
tags: ["Webhooks"]
---

# /webhooks

`POST /v1/webhooks`

## Request

- Base URL: `https://api.companydata.dk` (the document declares no server; this is the origin it was published from)
- URL: `https://api.companydata.dk/v1/webhooks`
- Auth: HTTP bearer

Register a new webhook endpoint.

The `url` must be HTTPS and respond `2xx` within 10 seconds. After creation, set
the list of CVRs to monitor with `PUT /v1/webhooks/{webhook_id}/cvr-filter` to start
receiving events.

**The `secret` field in the response is only returned here.** Store it now — it is
used to verify the HMAC signature on every incoming delivery and cannot be retrieved later.
A new secret can only be obtained by deleting and re-creating the webhook.

Returns `403` if you have reached your subscription tier's webhook limit.

## Request body

- CreateWebhookRequest: Request to create a webhook.
  - `name` string, required: Human-readable label shown in your account. Not sent to the webhook URL.
  - `url` string, required: HTTPS URL that will receive POST requests when matching events occur. Must respond with a 2xx status code within 10 seconds.
  - `event_types` EventType[]: Event types this webhook should receive. Defaults to all event types. See `GET /v1/webhooks/event-types` for the catalog.
  - `headers` object: Custom HTTP headers added to every delivery. Useful for routing or additional authentication on your endpoint.

## Response `201`

Successful Response

- WebhookWithSecret: A webhook configuration including the secret. Only returned on creation.
  - `webhook_id` string, required: Unique identifier for this webhook.
  - `name` string, required: Human-readable label.
  - `url` string, required: HTTPS endpoint that receives deliveries.
  - `active` boolean, required: Whether this webhook is currently delivering events.
  - `event_types` EventType[], required: Event types this webhook receives.
  - `headers` object, required: Custom headers added to every delivery.
  - `last_success_at` string, date-time, nullable: Timestamp of the most recent successful (2xx) delivery.
  - `last_failure_at` string, date-time, nullable: Timestamp of the most recent failed delivery attempt.
  - `consecutive_failures` integer: Number of consecutive failed deliveries. Reset to 0 on the next 2xx response. Reaching 10 auto-disables the webhook.
  - `disabled_reason` string, nullable: Set when the webhook is auto-disabled. `null` otherwise.
  - `created_at` string, date-time, required: When the webhook was created.
  - `secret` string, required: HMAC-SHA256 signing secret. Used to verify the `X-Companydata-Signature` header on every incoming delivery. **Store this immediately — it is never returned again.**

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/companydata/apis/companydata-dk-api.md) · [All operations](https://skmtc.dev/companydata/apis/companydata-dk-api/llms.txt) · [OpenAPI document](https://skmtc.dev/companydata/apis/companydata-dk-api/revisions/1cc6c361ae64?raw)