APIs & Events
Technical contracts, event semantics, and resilience patterns.
explanation • updated 2026-03-15
What this section solves
It defines how to build predictable integrations in a webhook-first model, reducing drift between temporary and final states.
Contract principles
- Mutating requests must use idempotency.
- Events are the final source of operational truth.
- Versioning and naming must be explicit per domain.
Recommended path
11) Read baseline contracts
Start with API essentials.22) Define event semantics
Apply Event conventions.33) Close execution safety
Validate Authentication and idempotency.44) Capture architecture rationale
Document trade-offs in Webhook-first architecture.
Integration quality criteria
| Criterion | Operational target |
|---|---|
| Duplicate processing | 0 duplicate side effects |
| Retry success | 100% with bounded backoff policy |
| Events without schema | 0 in production |
| Persistent 5xx errors | No backlog outside SLO window |
Start here
API essentials
Headers, authentication, and response patterns.
Event conventions
Naming, idempotency, and versioning.
Webhook-first architecture
Why the model is event-driven.
Authentication and idempotency
Scopes, retries, and exactly-once guarantees.
API reference
Map of Beacon endpoint groups.
Billing API
Checkout, subscriptions, and portal.
Stripe Connect API
Onboarding, refresh, and return flows.
Webhooks API
Ingestion, idempotency, and replay.
Fiscal API
Documents, reconciliation, and setup-state.
Observability API
Health, metrics, and operational alerts.
OpenAPI spec
Partial spec ready to evolve to Scalar/Redoc.