Developer API and Webhooks Documentation

How to read this document

Sections move from purpose → concepts → calculation process → worked examples → edge cases. Formula boxes use plain mathematical notation for clarity; they are conceptual summaries, not API contracts.

• Point lists call out operator-visible behaviour.
• Callouts mark warnings, limitations, or important qualifications.
• Worked examples use round numbers so you can reproduce the arithmetic by hand.

Purpose and contract

The developer API enables authorized automation over supported AccountHouse resources. Published endpoint schemas and version behavior, not examples alone, define the integration contract.

• Authenticate server-side
• Request only necessary access
• Handle errors and quotas
• Verify every webhook

Environment and base context

• Use the documented base URL and version.
• Keep test and production credentials separate.
• Confirm household scope.
• Do not infer undocumented fields or endpoints.

Authentication

API credentials identify an integration and must remain server-side. Never place a secret in browser bundles, mobile packages, public repositories, logs, or support messages.

Authorization and household scope

A valid credential is not permission to access every household or resource. Treat authorization failures as boundaries, not invitations to enumerate.

Requests and resource patterns

• Send supported content types.
• Use stable resource identifiers.
• Validate dates, currencies, and amounts.
• Paginate collections.
• Do not depend on response ordering unless documented.

Responses and errors

Handle status, structured error context, and retryability separately. Do not expose raw upstream errors to end users.

• Correct validation errors before retry.
• Refresh or rotate invalid credentials.
• Back off on transient or quota responses.
• Treat authorization denial as definitive unless permissions change.

Quotas and rate limits

Quotas protect availability and can vary by route, account, integration, or operational conditions. Integrations should be efficient without depending on a fixed unpublished ceiling.

Pagination and synchronization

• Follow documented cursors or page tokens.
• Persist checkpoints only after successful processing.
• Expect data changes between pages.
• Use update timestamps or supported sync fields carefully.
• Reconcile periodically.

Idempotency and duplicate prevention

Network retries can repeat a write. Use documented idempotency controls or integration-side stable operation keys where supported.

Webhook delivery model

Webhooks notify an HTTPS endpoint about supported events. Delivery can be delayed, duplicated, retried, or arrive out of order, so consumers must be idempotent and reconcile with the API.

• Acknowledge promptly.
• Queue durable processing.
• Deduplicate by event identifier.
• Do not assume ordering.
• Fetch authoritative resource state when needed.

HMAC signature verification

Verify the signature using the webhook secret and the exact raw request bytes under the documented scheme. Parsing and reserializing before verification can change the bytes.

• Use constant-time comparison.
• Validate the documented timestamp.
• Reject malformed or missing signatures.
• Keep current and rotated secrets isolated.
• Return no sensitive diagnostics to callers.

Freshness and replay resistance

Signature validity alone does not establish freshness. Validate documented timestamp context and deduplicate processed event identifiers.

Secret rotation

Logging and monitoring

• Log request or event identifiers.
• Redact credentials and sensitive payload fields.
• Measure latency, failures, retries, and dead letters.
• Alert on sustained failures.
• Retain only necessary diagnostics.

Testing checklist

• Valid and invalid authentication
• Cross-household denial
• Validation failures
• Pagination changes
• Quota and retry behavior
• Duplicate webhook events
• Out-of-order delivery
• Bad signature and stale request
• Secret rotation

Integration incident response

Privacy, advice limits, and what we do not publish

AccountHouse is a household tracking and organisation tool. It is not a bank, payment processor, tax advisor, or investment advisor. Forecasts, health scores, balances, and alerts are informational.

• Household data is scoped to your household; other families cannot see your ledger.
• Public documentation explains product behaviour and calculation concepts, not proprietary internals.
• Exact scoring weights, anomaly thresholds, cryptography parameters beyond high-level algorithms, and operational detection rules are reserved.
• API and webhook payloads can contain sensitive household data; minimize collection and retention.
• Exact quotas, abuse controls, internal detection thresholds, and infrastructure details are intentionally not published.