Subscriptions

Outbound webhook delivery (Apier → consumer)

REVERSE webhook. Apier POSTs this request to the URL the consumer registered via POST /api/v1/subscriptions when a change-archive event matches the subscription's filter. SDK generators that consume this OpenAPI 3.1 document SHOULD generate a typed RECEIVER (handler) for this operation, not a CLIENT. Verification: HMAC-SHA256 over <timestamp>.<raw_body> using the 64-character hex webhook_secret VERBATIM as the key — do NOT hex-decode. Compare against the v1 segment of X-Apier-Signature with a constant-time compare. Reject when |now - t| exceeds 300 seconds (replay protection). 7-attempt exponential-backoff schedule (1m / 5m / 15m / 1h / 6h / 24h between attempts) before abandonment; auto-disable after 6 consecutive 4xx responses (excluding 408 / 429). Event types are identified by the change object's (source, entity_type, change_type) tuple — the only event in v1, accounts.updated, is source=brreg, entity_type=annual_accounts, change_type=updated; subscribe with a filter selecting source brreg and entity_type annual_accounts.

postWebhookapierWebhookDelivery

Headers

X-Apier-SignatureXApierSignature required(unresolved $ref)

Stripe-style HMAC envelope. Verify before parsing the body.

X-Apier-Correlation-IdXApierCorrelationId required(unresolved $ref)
User-AgentUserAgent required(unresolved $ref)

Payload

subscription_idstring uuid required

Echoes the subscription that produced this delivery — useful for fan-out receivers that maintain multiple consumer-side records.

delivered_atstring date-time required

RFC 3339 UTC timestamp when Apier composed the body (close to but distinct from t in the signature header — t is the unix-seconds timestamp HMAC'd against the body).

attempt_numberinteger required

1-indexed attempt counter. 1 = immediate first delivery; 2-7 = retries after 1m / 5m / 15m / 1h / 6h / 24h. Receivers can use this to suppress duplicate side effects after the same (subscription_id, change.id) pair fires more than once because the previous attempt's response was lost in transit.

correlation_idstring uuid required

Same UUID as X-Apier-Correlation-Id. Repeated in the body so a logging pipeline that strips headers still has the join key.

Response

Receiver acknowledged the delivery. Apier resets the consecutive-4xx counter and drops the queue row.

Changes

Webhooks have no change history: a webhook is keyed by its event name rather than a path and method, so no recorded change can name it.