Subscriptions

Create a webhook subscription

Creates a Pro-tier change-detection webhook subscription. The plaintext webhook secret is returned ONCE in the 201 response and never again — store it client-side. Apier signs every delivery with HMAC-SHA256 over <timestamp>.<body> (Stripe-style header t=<unix>,v1=<hex> on X-Apier-Signature). Webhook URLs are SSRF-validated at create time AND at every delivery; a 7-attempt exponential-backoff schedule (initial try plus retries at 1m / 5m / 15m / 1h / 6h / 24h) is exhausted before a delivery is abandoned. After 6 consecutive 4xx responses (excluding 408 / 429 — receivers asking us to back off don't burn the counter) the subscription auto-disables. Outbound delivery contract: receivers should expect WebhookDeliveryHeaders plus a JSON body matching WebhookDeliveryEvent (both in components.schemas). Supports the optional Idempotency-Key header: a retried create presenting the same key and body replays the original 201 (including the once-only secret) with Idempotent-Replay: true instead of creating a duplicate subscription.

post/api/v1/subscriptions

Request

  • Base URL: https://www.apier.no
  • URL: https://www.apier.no/api/v1/subscriptions
  • Auth: HTTP bearer

Headers

Idempotency-Keystring

Optional client-chosen key that makes this write safely retriable. When the same key is presented on a subsequent request with the same body, the gateway returns the original response (with Idempotent-Replay: true) instead of re-executing the write. Reservation is scoped to (consumer, endpoint, key) so the same key on different endpoints or different consumers does not collide. TTL: 24 hours. The key must be 1–255 printable ASCII characters — a v4 UUID or ULID is the recommended format. Keys are SHA-256 hashed before storage so they may safely carry client-internal identifiers.

Request body

webhook_urlstring uri required

Public HTTP(S) URL. http:// is rejected at runtime when VERCEL_ENV === "production" (the env-loader superRefine fails-closed there); in non-production environments a Development/Preview deploy can opt into http:// via the WEBHOOKS_ALLOW_HTTP=true env var (default false). The schema pattern accepts both http and https case-insensitively (RFC 3986 §3.1 — scheme names are case-insensitive) so a HTTPS:// spelling from an aggressive normaliser isn't rejected at the contract layer; the runtime gate handles the production-only HTTPS enforcement. Private CIDRs / .local / metadata-endpoint hostnames blocked at create AND at every delivery.

Response

Subscription created. The plaintext webhook_secret is returned exactly once.

successtrue required

Example response

{
  "_meta": {
    "rulebook_version": "v1.0.0",
    "source": "apier.no",
    "data_source": "Brønnøysund Enhetsregisteret + Apier Universal Rulebook",
    "schema_version": "1.0.0",
    "legal_basis": "NLOD — public registry reuse",
    "response_timestamp": "2026-04-24T12:00:00.000Z",
    "response_hash": "sha256:0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef",
    "source_snapshot_id": "brreg-2026-04-24T02:00:00.000Z",
    "cost_nok": 0.5,
    "wallet_remaining_nok": 9.5,
    "spend_cap_remaining_nok": 12.5
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.