Contract v1 · generated reference

RuntimeHandler.connectWebhook

OP-RUNTIME-CONNECT-WEBHOOK is a webhook operation owned by Partner.

Authority and transport

Actor: verified provider
Authentication: provider signature
Authorization: signature and environment isolation
Resource boundary: server-derived from verified payload and stored state
Transport: WEBHOOK
Deployed export: connectWebhook
Trigger: onRequest; HTTPS onRequest; invoker public; cors false
App Check: NOT_APPLICABLE
Canonical source: functions/src/properties/partner/payouts/connect-webhook.ts

Request schema

Request parameters for RuntimeHandler.connectWebhook
Field	Required	Schema
`rawBody`	Yes	`Stripe v2 thin-event JSON bytes (id, type, livemode, related_object), maximum 1,000,000 bytes`
`stripe-signature`	Yes	`timestamp plus one or more v1 HMAC digests over the raw body`

Response schema

HTTP 200 { received: true, outcome: APPLIED | ACK_ONLY_RETURN | UNSUPPORTED_EVENT_TYPE | MALFORMED_RELATED_OBJECT | UNMATCHED_ACCOUNT } or { deduplicated: true }; governed JSON error otherwise

States, consistency and recovery

State path: RECEIVED → SIZE_AND_SIGNATURE_VALIDATION → THIN_EVENT_SHAPE_CHECK → ENVIRONMENT_MODE_CHECK → INBOX_CLAIM_OR_DEDUPLICATION → AUTHORITATIVE_PROVIDER_ACCOUNT_READ → READINESS_APPLIED_OR_INERT → ACKNOWLEDGED_OR_PROVIDER_RETRY
Reads: Connect inbox lease, the connectAccounts account-to-organization mapping and an authoritative provider account read; the event payload is never trusted for readiness
Writes: connectWebhookEvents inbox row plus organization readiness, listing suspension and outbox signals applied only from the provider read
Transaction: inbox lease transaction, then the readiness application transaction, then acknowledgement
Idempotency: Stripe event id with a recoverable inbox lease; a PROCESSED row deduplicates
Concurrency: inbox lease plus a fresh provider read before any organization write
Retry/replay: duplicate and out-of-order safe; a processing failure leaves the row FAILED and returns HTTP 500 so the provider retries; a busy lease returns 503 with Retry-After
Rate limits: Provider delivery policy; busy processing returns HTTP 503 with Retry-After: 60.
Audit: provider event id, event type and outcome on the inbox row; never raw body, signature or account details

Error contract

Exact public webhook response families for Connect thin events; the shared signature verifier reports payments/* codes and processing details collapse to a privacy-safe connect/* failure code. Never treat an unknown error as success.

raw body unavailable
connect/payload-too-large
payments/missing-signature
payments/invalid-signature
payments/stale-timestamp
payments/secret-wrong-kind
connect/invalid-event
connect/invalid-app-environment
connect/provider-mode-mismatch
connect/event-processing-in-progress
connect/processing-failed

Producer test references

Evidence tier: SEMANTIC_CORE_REFERENCE.

Reviewer-mapped semantic/core references

functions/test/estate-service-export-parity.test.js
- the three HTTP services are intentional public handlers with least secret binding
functions/test/payments-webhook.test.js
- a correctly signed, fresh payload verifies
- a tampered body is rejected
- a wrong secret is rejected
- a replay outside the 300s window is rejected even though the signature is valid
- a missing signature header is rejected
- a malformed header is rejected
- multiple v1 signatures are accepted if any matches (secret rotation)
functions/test/recovery-connect-journey.test.js
- J1 provider says active → verified + payoutsEnabled + COMPLETE, from the read
- J5 a revoked capability withdraws payouts, suspends published listings and signals the catalogue
- J6 a live-mode account is refused in UAT
- J2 the same event id is deduplicated at the inbox; a second application is a no-op
- J3 an event for an account we do not know touches no organisation
- J4 a return-url visit is ack-only and never completion
functions/test/recovery-connect-readiness.test.js
- thin events: only v2 account events with a well-formed related object parse
- account ids are validated by shape

Each cited test name is checked against the referenced file by the documentation suite, so a renamed or removed producer test breaks this page instead of leaving a stale claim.

Protocol or inventory references

functions/test/estate-service-inventory.js

These references prove export, wrapper or protocol behavior only. They are not counted as complete operation semantics.

Example availability

NOT_PUBLIC_TRANSPORT: This handler is provider- or platform-invoked and has no public client invocation.

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