Contract v1 · generated reference

Webhooks

Signed provider ingress is an at-least-once, out-of-order transport.

The deployed webhook exports are connectWebhook and paymentsWebhook. Both are onRequest handlers with CORS disabled and no App Check surface: the Stripe signature over the raw request body is the only admission control. Verify it before parsing; see the signature procedure.

Payments webhook

paymentsWebhook receives payment-intent events and is the only writer of a confirmed booking. Accepted event types are listed in the event catalogue.

Connect webhook

connectWebhook receives Connect thin events for partner payout readiness. A thin event carries only an id, a type and a related-object pointer; its payload is never trusted for readiness. The handler re-reads the account from the provider and applies what the provider says now. A live-mode event is refused in UAT before anything is read, and an account-link return is acknowledged and logged only, because a return is never completion.

v2.core.account.updated
v2.core.account[configuration.recipient].capability_status_updated
v2.core.account[requirements].updated
v2.core.account_link.returned

Delivery contract

Reject missing, malformed or stale signatures before any domain write.
Reject a live provider event in local or UAT, and a test event in Production.
Claim the provider event id in the inbox before applying state.
Treat duplicate, late, regressive and unhandled events as explicit inert outcomes.
Return only after the authoritative transition and required records commit.

Transport acknowledgement does not replace domain-state inspection. Correlate on the provider event id without logging raw payloads, signatures or customer data.

Common integration contract

Sandbox and Production are isolated

Run examples only in a governed sandbox or local emulator. Sandbox identities, App Check tokens, payment fixtures and data do not grant Production access. The typed ports do not ratify a public numeric quota; enforcement may be stricter. Honor RATE_LIMITED and the server's retry-after value.

Authentication and authorization

Firebase Auth proves identity. App Check proves the approved app where a callable requires it. Roles, organization membership, requester identity and resource ownership are derived and rechecked by the server.

Authentication guide

Errors and recovery

Stable error codes distinguish validation, denial, conflict, expiry, authority pending, rate limiting and temporary unavailability. Never infer success from an HTTP redirect or a browser state.

Error catalogue

Idempotency, concurrency and retry

Reuse an idempotency key only for an identical retry. A new intent needs a new key. Preserve version preconditions and reload after a conflict.

Retry guidance

Changes and escalation

Check compatibility before adopting a new contract version. Review the changelog, service status and support guidance before retrying a persistent failure.

Changelog Service status Developer support

Common failure families
Family	Client decision
Authentication / authorization	Refresh or step up only when instructed; do not retry a denial unchanged.
Validation / conflict / expiry	Correct or reload state, then obtain confirmation for a new intent.
Rate limited / unavailable	Honor retry-after and use bounded backoff; inspect service status.
Unknown / server	Fail closed and escalate with a privacy-safe correlation id.

Executable network examples are published only when the exact wire schema is producer-proven. Check the selected operation's example-availability status; an unresolved schema is a release blocker, not permission to guess.

Verified examples and local-only recovery snippets