Rail webhooks — how Crossdeck receives signed events from your payment rails

Crossdeck operates the receivers for every payment-rail webhook so you don't have to write one. Apple App Store, Stripe Connect, and Google Play each push signed events to a Crossdeck-owned endpoint; we verify the signature, dedupe the event ID, project the change into a hash-chained ledger, and recompute your customer's state — all before the event ever shows up in your dashboard. Stripe is zero-config after OAuth. Apple and Google need a small one-time setup, documented below.

TL;DR

• Three rails, one shared pipeline. Apple App Store Server Notifications V2, Stripe Connect platform webhooks, and Google Play Real-time Developer Notifications all flow through the same verify → dedupe → journal → project sequence.
• Verified at the edge before any write. Apple JWS chain, Stripe HMAC-SHA256, Google Pub/Sub OIDC. A malformed signature is rejected with a 4xx before we read anything from your project.
• Bank-grade idempotency on every event ID. Apple's notificationUUID, Stripe's evt_ ID, Google's per-message composite key — re-deliveries are no-ops, recorded once.
• Forward-only hash-chained ledger. Every accepted webhook becomes one append-only entry. The ledger is never edited; corrective events get their own entries. The audit trail is permanent and replay-detectable.
• Stripe is zero-config after OAuth. You click "Connect Stripe" in the dashboard and Crossdeck's platform-level webhook starts receiving events from your connected account automatically. Nothing to paste anywhere.
• Apple and Google need a small one-time setup. Paste a URL into App Store Connect plus upload a .p8 key; or paste a Pub/Sub topic name into Play Console plus upload a service account JSON. About five minutes each.
• You never write a webhook handler. No HMAC verification code, no idempotency table, no retry logic. The receivers run inside Crossdeck and surface state through the dashboard and the SDKs (the SDK's reactive onEntitlementsChange listener + server-side getEntitlements()). Outbound push-to-your-backend webhooks are roadmap — see Inbound vs outbound below.

Inbound vs outbound

The asymmetry is intentional. Inbound is hard — three rails, three signature schemes, three retry models, three error semantics — and getting any of it wrong leaks revenue or grants unpaid access. Outbound is comparatively easy, and adding it is a feature that lands on top of a finished inbound layer rather than a precondition. The inbound layer described here is finished.

The shared pipeline — what every rail webhook does at Crossdeck

Each rail's receiver function lives in backend/src/webhooks/ and follows the same six-step sequence. The shape never changes; only the rail-specific verification primitive and the routing primitive vary.

Two contracts are enforced at compile time inside the spine:

• Journal-first writes only. Catalog / subscription / purchase mutations route through writeProjection, which requires journal evidence as a parameter. There is no overload that accepts a "skip journal" flag.
• Atomic journal + projection. The journal append and the projection write are committed inside one Firestore transaction. A crashed write never leaves a ledger entry without state, or state without a ledger entry.

Apple — App Store Server Notifications V2

What Apple sends

Apple delivers every subscription, purchase, refund, and lifecycle event as a JWS-signed payload to the URL you registered. Crossdeck's receiver handles the full V2 taxonomy. The notification types we map and react to include:

One-off StoreKit purchases (Consumable, Non-Consumable, Non-Renewing) ride the same notification stream — Crossdeck dispatches on transaction.type and writes them to a separate purchases ledger instead of the subscriptions one.

Verification — JWS chain to Apple's root

Apple signs every notification with a leaf certificate; the leaf certificate is signed by an intermediate CA, which is signed by Apple's root. Crossdeck's receiver decodes the JWS, verifies the chain, and rejects anything that doesn't terminate at a known Apple root certificate. The verifier also re-verifies the inner signedTransactionInfo and signedRenewalInfo JWS payloads inside the same notification — Apple signs every field, end to end.

Implementation: the verifier is built per-call from buildAppleVerifier(env, config) in lib/apple-verifier.ts using Apple's official SignedDataVerifier from @apple/app-store-server-library. Online checks (cert revocation) are enabled. The bundle ID from your project config is part of the verifier construction — the verifier rejects payloads whose bundleId doesn't match what you registered.

Because the production endpoint and sandbox endpoint share a URL, the receiver tries the production verifier first and falls back to sandbox on failure. If both fail, it returns 401 Signature verification failed and writes nothing.

Configuration — what you do

Apple needs three things on Apple's side and one thing on ours, in either order:

1. Upload your .p8 key + Key ID + Issuer ID in Dashboard → Payment rails → Apple App Store. The key is what Crossdeck uses to authenticate back to the App Store Server API during reconciliation. The Key ID and Issuer ID come from App Store Connect → Users and Access → Keys → In-App Purchase.
2. Set the App Store Server Notifications V2 URL in App Store Connect → your app → App Information → App Store Server Notifications. Paste:

   https://api.cross-deck.com/v1/webhooks/apple/{your-projectId}

   Your dashboard's Developers → API page renders the exact URL with your projectId interpolated, with a one-click copy button.
3. Select both Production and Sandbox notification environments so test purchases ingest too. Apple sends sandbox notifications to the same URL with an environment field on the inner payload; Crossdeck routes them to your sandbox ledger automatically.

That's it. Once those land, every signed event from Apple flows through the receiver and into your dashboard. There is no second-step "now go configure idempotency" or "now go register webhook secrets" — Apple signs with their leaf cert and Crossdeck verifies against their root chain; no shared secret is needed.

Stripe Connect — zero-config after OAuth

This is the marquee feature of Crossdeck's webhook layer. The Stripe section is short on purpose: there is almost nothing for you to do.

The shipped flow

One Stripe webhook endpoint is registered at the Crossdeck platform level and receives events from every connected account that any of our developers has OAuthed. When you click "Connect Stripe" in the dashboard, the OAuth flow exchanges the authorization code for a connected-account token and writes the connected account ID into our connectedAccountIndex. From that moment forward, every webhook Stripe fires for events on your account — created, updated, deleted, paid, failed, refunded, disputed — lands at our platform endpoint, gets routed to your project via event.account lookup, and flows through the same pipeline as Apple and Google.

The platform-level Stripe webhook is registered once by Crossdeck against the platform's Stripe Connect application. Connected accounts inherit that subscription automatically — that's how Stripe Connect works. You don't paste a URL into a Stripe dashboard. You don't copy a signing secret. You don't configure event types. You don't write a verification function. The webhook is already running; OAuthing just routes events that account emits into your ledger.

What Stripe sends to us

Crossdeck subscribes the platform webhook to a fixed, canonical list of event types. These are exactly the events that move subscription, purchase, or catalog state — anything else from Stripe is ignored at the edge. The handled list, from HANDLED_EVENT_TYPES in backend/src/webhooks/stripe-platform.ts:

Verification — Stripe-Signature HMAC-SHA256

Every Stripe webhook arrives with a Stripe-Signature header. The receiver verifies it using Stripe's official stripe.webhooks.constructEvent(rawBody, signatureHeader, platformWebhookSecret), which performs an HMAC-SHA256 compare in timing-safe constant time and respects Stripe's replay window. The platform signing secret lives in Google Cloud Secret Manager — never in environment files or Firestore. A failed signature returns 401 Signature verification failed immediately.

After signature verification, the receiver also reconciles the event by calling stripe.events.retrieve(event.id, { stripeAccount }) back into the connected account. This second call fetches the canonical event payload directly from Stripe — upgrading the trust level from "provider-attested via signed webhook" to "provider-attested AND independently re-fetched." Re-fetched values are used for the actual ledger write; the inbound webhook payload is treated as a notification, not the source of truth.

Configuration — just OAuth

The complete developer task list for Stripe:

1. Dashboard → Payment rails → Stripe → Connect.
2. Complete Stripe's OAuth screen.
3. Done.

From the moment the OAuth callback completes and the connected account ID is written into connectedAccountIndex, every webhook Stripe sends for that account flows into your ledger. No URLs pasted, no secrets copied, no event types selected.

Google Play — Real-time Developer Notifications

Transport: Pub/Sub, not HTTPS

Google Play doesn't push webhooks over HTTPS like Apple and Stripe do. Instead, the Play Console publishes a message to a Google Cloud Pub/Sub topic. Crossdeck has a push subscription on that topic that triggers our googlePlayWebhook function on every publish.

This is operationally bank-grade by virtue of the transport: Pub/Sub provides at-least-once delivery, automatic retry with exponential backoff, and dead-letter forwarding for poison messages. Crossdeck doesn't have to re-implement any of that; we just process each message idempotently and let Pub/Sub handle redelivery on failure.

What Google sends

Verification — Pub/Sub OIDC plus Play Developer API re-fetch

Google Play notifications carry two layers of verification:

1. Pub/Sub OIDC. Google Cloud's push-subscription delivery includes an OIDC token signed by Google's service account. Cloud Functions verifies the OIDC token before invoking our handler; an unauthenticated message never reaches the receiver code at all. This is enforced at the platform layer.
2. Play Developer API re-fetch. The RTDN payload itself carries minimal data — a purchaseToken, a numeric notification type, a package name. To get the authoritative purchase shape (price, currency, account hint, full lineage), Crossdeck calls purchases.subscriptions.get / purchases.subscriptionsv2.get on the Play Developer API directly using your uploaded service account credentials. Even if a Pub/Sub message could somehow be forged, the actual purchase data is fetched directly from Google — there is no payload-based attack surface.

Configuration — what you do

1. Upload your Play service account JSON in Dashboard → Payment rails → Google Play. The service account needs the "View financial data" and "Manage orders" permissions on your Play account, granted in Play Console → Users and permissions.
2. Set the Pub/Sub topic name in Play Console → Monetization setup → Real-time developer notifications. Paste:

   projects/crossdeck-47d8f/topics/gplay-rtdn

   That's a single shared topic in the Crossdeck Google Cloud project — your messages are routed by their packageName field, not by topic isolation.
3. Grant Pub/Sub Publisher permission to Google Play's developer-notifications service account on that topic. Google requires this and surfaces the exact instructions in Play Console; the service account email is [email protected].
4. Click "Send test publish" in Play Console. Crossdeck receives the test notification, acknowledges it as a no-op, and surfaces it in your dashboard's audit log — confirming the wire is up before any real money moves.

Bank-grade guarantees — verified per event

Every accepted webhook crosses the same four-property bar before it touches your ledger. The table below maps each rail to the primitives that enforce each property.

Every receiver writes an audit row on every decision — applied, no_op, or rejected. Re-deliveries are recorded once. Signature failures are recorded with signatureVerified: false. Reconciliation failures are recorded with the failed-step name and message. The audit log is the canonical answer to "what did Crossdeck do with that event?"

The hash-chained catalog ledger

Every accepted webhook becomes one entry on a single forward-only ledger per project. The ledger is append-only, hash-chained between entries, and signed at append time. Three properties follow:

• Replay-detectable. Any attempt to alter a prior entry breaks the chain at every entry after it. Verification walks the chain and confirms each link.
• Permanent audit trail. No ledger entry is ever edited. Corrective events — a refund, a plan downgrade, a manual operator action — get their own entries that reference the prior state. The "before" lives in the chain.
• Deterministic state. Customer entitlement state at any wall-clock time can be reconstructed by replaying the ledger forward to that time. The live state cached in the customer document is just the current playhead; the chain is the source of truth.

Subscriptions, one-off purchases, refunds, disputes, plan changes, catalog changes (product / price create / update / delete) — each becomes one entry. The atomic-write contract (journal + projection in one transaction) guarantees you never see a state that exists without its corresponding ledger entry.

The ledger is read implicitly: the dashboard's customer state, the Activity timeline, the audit log, and the entitlement projection all flow from it. You don't have to query the ledger directly to benefit from it; it's the substrate that makes the rest correct.

What you see in the dashboard after a webhook lands

The dashboard is the consumption surface for everything the receivers produce. After any rail webhook lands and the ledger entry commits, four things update inside the second-to-five-second window for each rail:

• Customer record. The status pill flips (TRIAL → ACTIVE on conversion, ACTIVE → BILLING_RETRY on a failed renewal, ACTIVE → REFUNDED on a refund). MRR recomputes if the change affected billing. The dashboard's Customer Overview reflects the new state on the next Firestore snapshot.
• Activity timeline. A new row appears with rail context — which rail emitted the event, the raw event type, the Crossdeck-derived signal (trial_converted, billing_recovered, etc.), and a link back to the original event ID on the rail's own dashboard.
• Errors page. If verification failed or reconciliation errored, the failed event appears with the failure reason. The signature-failed path never leaves project state in an inconsistent shape — failures are observable on the Errors page; state remains last-good.
• Audit log. The identity journal entry (e.g. rail_attached when a Stripe metadata.crossdeck_ref linked a Stripe sub to an existing customer) shows up with the evidence kind (stripe_webhook_signed, apple_jws_verified, google_pubsub_verified) and the JTI of the originating event.

The dashboard surfaces consumption; the receivers do the work. Every state change a customer-facing surface shows is traceable to a verified, signed, deduped event with an entry on the ledger.

Failure modes and recovery

The receivers are designed to surface failure cleanly without ever silently dropping a real event. The failure modes break down into four categories, each with a defined response:

No real event is ever lost. The retry windows of all three rails are designed for exactly this — a downstream system that briefly stalls, recovers, and processes the queued event on the next delivery. Crossdeck's idempotency guarantees the eventual processing is exactly-once even though the delivery is at-least-once.

Sandbox vs production

Every rail provides a separate sandbox / test environment with its own delivery path:

• Apple. Sandbox notifications are sent to the same Production V2 URL with an environment: "Sandbox" field on the inner payload. Crossdeck's receiver decodes the env from the signed payload and routes to your sandbox ledger.
• Stripe. Connected accounts can be in test mode or live mode; the platform-level webhook receives both, and the receiver routes via event.livemode on each event.
• Google Play. Play license-tested account purchases flow through the same RTDN pipe as real purchases. Disambiguation happens at the Play Developer API re-fetch step; for v1, RTDN payloads default to production env and license-test purchases are flagged during reconciliation.

The dashboard's environment switcher (top-right, "Live · Production" vs "Sandbox") routes the entire UI between the two ledgers. Test purchases never contaminate live MRR; sandbox metrics never leak into production reports. Identity, entitlement, catalog, and activity surfaces all partition cleanly.

Latency expectations

Webhook → dashboard update latencies, measured end to end (rail emits event → dashboard reflects the new state via Firestore snapshot):

These latencies are acceptable for any UX that isn't strictly real-time-critical — paywall unlocks, entitlement grants for desktop / web SDKs, dashboard customer-state updates, churn alerts. For SDK-side entitlement gating that must answer in microseconds, the SDK's local cache covers the synchronous read path; the cache is invalidated by the same webhook-driven server-side update described above.

What about the OAuth window?

There is one narrow window worth calling out explicitly: between the moment you click "Connect Stripe" in the dashboard and the moment Crossdeck finishes processing the OAuth callback. The wall-clock duration is typically two to three seconds. During that interval, your connected account ID is not yet in connectedAccountIndex, so a Stripe webhook that arrives mid-flight would route to "no project found" and return 200 without writing.

This is handled by Crossdeck's Stripe discovery backfill: the moment the OAuth callback writes the connected account into Firestore, a separate Firestore-trigger function (onStripeRailConnect) picks it up and runs a read-only discovery scan that paginates through every subscription, customer, and product on the connected account. Anything that existed before the OAuth — including events that fired during the OAuth window itself — is enumerated and projected into your ledger on the first scan. No events are lost.

For Apple and Google, there is no analogous window. The URL / topic name is the same forever; you paste it once when configuring the rail, and the first event after that lands at your endpoint. Reconciliation against the App Store Server API and Play Developer API provides equivalent historical-state backfill for those rails when their config first lands.

Related

• Identity verification — how rail events drive identity decisions, including rail_customer_created and rail_attached journal entries and the evidence kinds (stripe_webhook_signed, apple_jws_verified, google_pubsub_verified) that justify them.
• Entitlements — how the ledger state composes into the entitlement projection that SDKs read.
• Connect Stripe — the OAuth flow whose callback registers your account for the platform webhook described here.
• Receiving Crossdeck webhooks — the outbound side (Crossdeck → your backend); currently roadmap.
• Source maps — unrelated to webhooks but in the same dev-infrastructure family.

Receivers live in backend/src/webhooks/ — apple.ts, stripe-platform.ts, google.ts. Verification primitives in backend/src/lib/apple-verifier.ts. Shared spine in backend/src/catalog/spine.ts. Identity journaling in backend/src/lib/identity-journal.ts.