Thin or Snapshot Events? Prove Stripe Migration Safety Before Dual Delivery

A Stripe thin-event migration is not proven by a smaller payload, a green 200, or a successful sandbox demo. The engineering question is narrower and harder: can two handlers, receiving differently identified representations of one logical event, converge on an acceptable business result when deliveries overlap, resource state changes between observations, workers crash, and replay occurs later?

That question matters now because Stripe documents thin events for API v1 resources as a private preview, while established thin-event support also exists for API v2 resources. Eligibility, field availability, software development kit (SDK) behavior, event-family support, and preview API versions therefore belong in the migration contract, not in an assumption.

This playbook treats the existing snapshot handler as authoritative until evidence supports a reversible cutover. It focuses on one fictional sandbox customer-synchronization service, not live payment or refund operations. The evidence pack we want at the end is operational: correlation works, durable states distinguish receipt from completion, shadow differences are explained, crashes are recoverable, replay consults local completion history, and rollback preserves that history.

Define the migration decision and business invariant

Start by naming the business invariant before discussing formats. For the worked example, assume a service mirrors selected Stripe Customer fields into an internal customer table. The authoritative behavior is: for each supported customer event, eventually converge the local customer record to the resource state required by the declared synchronization contract, without applying the same logical operation twice. This is a local operating model, not a Stripe guarantee.

The snapshot handler remains authoritative during evaluation. That matters because migration should not silently combine three changes: event format, business semantics, and failure-handling model. If the current handler has weaknesses, record them separately and decide whether fixing them is a prerequisite or an independent change. Broader third-party API integration foundations are useful context, but this decision is specifically about Stripe event identity and recovery.

A smaller delivered payload is not itself an invariant. Neither is “both handlers returned 2xx.” The invariant must describe business state and the conditions under which the operation is considered complete. Stripe explicitly recommends asynchronous webhook handling and warns that event delivery order is not guaranteed, so the consumer must own ordering tolerance and durable work state.

Decision checklist: name the event family; name the local effect; name the authoritative handler; name the completion evidence; name the rollback owner. If any answer is “whichever handler gets there first,” the design is not ready for dual delivery.

Verify private-preview access and version contracts

Stripe’s event-destination documentation marks thin events for API v1 resources as private preview. That is distinct from the established API v2 thin-event model. Do not turn the preview into a general-availability claim, and do not infer that every Stripe account can create API v1 thin destinations.

The migration guide adds an important prerequisite: snapshot_event, used to correlate an interoperability thin event to its original snapshot event, requires a preview API version. Its JavaScript and event-destination examples use 2025-11-17.preview. A separate webhook example shows 2026-08-26.preview for event-destination API calls. Those strings are documentation examples from different pages, not evidence that either is correct for every enrolled account.

Treat “stable notification shape” carefully. Stripe describes thin notifications as unversioned while the migration guide still requires a preview API version for private-preview behavior, and it states that fetched resource details use your current API version. An unversioned notification does not make the related-resource schema unversioned, nor does it remove SDK upgrade work.

There is also a documentation-scope wrinkle worth recording: the same event-destination page announces API v1 thin events in private preview near the top while its high-level comparison table still describes thin-event creation in API v2 terms. Do not silently “resolve” that text yourself. Treat the private-preview migration guide and the enrolled account’s observed behavior as the scoped evidence for API v1 interoperability.

Stop: do not enable candidate writes if preview access is absent, the required correlation field is unavailable, or the tested account/version combination is not recorded.

Separate notification, event and resource state

A reliable migration contract distinguishes four observations that are easy to collapse into “the webhook”: the delivered notification, the complete event, the related resource, and the local business operation. Stripe’s overview says snapshot events carry a point-in-time object representation and that this data can be stale when processed; thin notifications are lightweight and can lead to fetching the complete event or related resource.

Write those observations down as separate contract elements. That is more specific than describing a single “Customer event” schema, because each element has a different owner and time meaning. The notification contract is owned at the delivery boundary; the event contract preserves event context; the resource contract is observed through a later API call; the local-operation contract is yours.

Refonte’s guide to documenting event-driven API contracts provides broader documentation context, but the migration artifact here should go further by recording correlation, observation time, fetch dependency, write authority, and recovery state. A schema diagram without those operational facts is insufficient for deciding whether the two handlers are behaviorally interoperable.

For snapshot events, Stripe’s v1 Event object records the API version used to render data, and says the contents of data do not change later. Retrieval of an older event under a newer API version does not rewrite that historical event structure.

A historical event view versus a current resource fetch

Suppose customer.created was generated when cus_SYN_42.name = "Aster Labs". Before a worker processes the event, another request updates the customer to "Aster Systems". The snapshot event can still show the earlier representation, while a later resource fetch can return the newer state. Stripe explicitly recommends fetching the latest resource when current data matters.

Neither value disproves the other. They answer different questions. “What did the event contain?” is historical. “What should my mirror contain now?” can be current-state oriented. Therefore shadow comparison needs a declared oracle. Exact payload equality is appropriate only when the business contract truly requires equal historical representations.

For the fictional synchronization service, the proposed contract is current-state convergence. The shadow oracle therefore compares the intended upsert after normalization, not whether both handlers observed identical names at identical milliseconds.

One logical event across two delivery identifiers

The private-preview migration guide says that, during interoperability migration, when one action produces both versions, the thin event includes snapshot_event containing the original snapshot event ID. Stripe recommends using that shared value for cross-handler deduplication during overlap.

Do not generalize that statement to every thin event. The guide speaks about interop events during this migration. A local identity rule should therefore be explicit:

A prudent local key can namespace this identity by environment and relevant account/context, for example sandbox:acct_sbox_A12:evt_snap_SYN_001. That namespace is a proposed consumer design to prevent accidental cross-environment or cross-account conflation; it is not a Stripe field.

Verify signatures before durable acceptance

Signature verification belongs before acceptance. Stripe requires the raw request body for verification and generates a unique signing secret per endpoint; test and live secrets also differ. The private-preview migration guide specifically tells teams to store the thin destination secret separately from the snapshot secret.

The critical boundary is what happens before you acknowledge delivery. Stripe recommends returning a successful response quickly and processing asynchronously. From a consumer-recovery perspective, “quickly” should not mean “before anything durable exists.” If a handler verifies, returns 200, and crashes before persisting work, Stripe has evidence of delivery but your system may have no recovery record. That loss window is an engineering inference from the acknowledgement boundary, not a Stripe guarantee.

A bootstrap endpoint that verifies and acknowledges is useful for proving routing, and Stripe’s migration guide starts that way. It is not a completed processor. The production acceptance path needs a durable handoff that survives process death. For adjacent principles, Refonte’s API security and observability article provides broader context; Stripe remains the authority for its signing requirements.

Stop: no dual writes until a crash after acknowledgement can still be recovered from a durable local record.

Build an explicit processing-state ledger

A deduplication row is not proof of completion. Stripe’s undelivered-event guide itself distinguishes “processing” from “processed” in its sample recovery logic, which is the right conceptual direction even though a production design needs clearer ownership and crash semantics.

For this migration, use at least two identities: transport identity tells you what arrived; business-operation identity tells you what must happen once. A single logical work item may have two receipts during overlap.

Proposed pseudocode schema: not executed against Stripe or a database:

-- Local design only; synthetic column names.
event_work(
  env, account_context, logical_event_key PRIMARY KEY,
  event_family, state, lease_owner, lease_until,
  attempt_count, last_error, completed_at, operation_hash
)

event_receipt(
  env, account_context, transport_event_id PRIMARY KEY,
  logical_event_key, format, received_at
)

The core invariants are local: a receipt can exist without completion; only one active lease owns a work item; an expired lease can be reclaimed; completed is written only with evidence of the business effect; and rollback never deletes these records.

The operation_hash is optional but useful in shadowing: it can represent a normalized intended operation such as upsert-customer(cus_SYN_42, normalized-fields-v3). It should not contain secrets or full customer payloads.

Close the gap between deduplication and side effects

Stripe’s migration guide demonstrates a table where inserting a shared key prevents the second handler from processing the same logical event. That solves one overlap problem, but the simplified claim-then-effect pattern has a crash gap: a process can insert the “processed” key and die before the business effect. A retry then sees the key and skips permanently. This is analysis of the sample’s boundary, not a claim that Stripe presents the snippet as a complete transactional architecture.

Atomic local changes and recoverable claims

For a local database effect, put the business update and completed transition in the same transaction when they share a transactional store. The lease claim can occur earlier, but it must not itself mean success. On worker death, a recovery worker reclaims the item after the lease expires.

For the customer mirror, a transaction can: lock or compare the work row; upsert the local customer projection; set the operation version/hash; mark the work completed; and commit. A crash before commit leaves neither the business update nor completion committed. A crash after commit leaves both visible.

If the work claim and business state cannot share a transaction, store enough evidence to reconcile. The test suite must inject crashes both before and after the effect boundary.

External effects and request-idempotency limits

Inbound deduplication and outbound request idempotency solve different problems. The inbound ledger answers “have we completed this logical event?” An outbound idempotency key answers “is this retry of my request the same request?” Stripe documents that idempotency results may be pruned once keys are at least 24 hours old; reuse after pruning can create a new request.

Therefore an outbound Idempotency-Key is not a permanent completion ledger and cannot guarantee globally exactly-once side effects. Persist the outbound operation key, request fingerprint, provider resource/operation ID when available, last known outcome, and reconciliation status. After a timeout with an uncertain result, reconcile before issuing a new non-idempotent effect, especially when the original key may be outside its retention window.

The worked example performs only an internal customer-table upsert. It does not send live payments, refunds, or other financial side effects.

Run the customer-synchronization worked example

The following fixture is entirely synthetic. Assume preview enrollment has already been verified in a Stripe sandbox; customer.created and its preview counterpart v1.customer.created are confirmed supported for that account; the tested SDK/version combination exposes snapshot_event; and both handlers persist into the shared ledger described above. No execution result is claimed.

The proposed 60-second lease is a local test choice, not a Stripe recommendation. In production, set it from measured worst-case processing time plus safety margin, and make renewal observable.

The interesting part is the resource update before processing. The snapshot delivery can contain “Aster Labs,” while a later fetch can return “Aster Systems.” For this service, the business contract says the mirror should converge to the latest retrievable customer state, so the expected terminal local value is “Aster Systems.” A shadow comparison that flags this as a raw-payload mismatch but accepts the normalized business outcome is behaving correctly.

Recovery also demonstrates why “row exists” is insufficient. At T0+4 seconds the work row exists, but the operation is not complete. Only the transaction at T0+65 seconds can move the item to completed.

Fixture acceptance checklist: both delivery IDs are retained; one logical work item exists; concurrent retries cannot create a second work item; stale claims are reclaimable; the latest-state business rule is explicit; and completion survives handler rollback.

Compare shadow behavior against the right oracle

Stripe’s migration guide recommends shadow mode: fetch event details and related objects, log intended actions, and avoid database writes until behavior is understood. It suggests at least 24–48 hours of monitoring and says divergence should be investigated before production impact. Time is useful for exposure, but elapsed hours alone are weak acceptance evidence; event-family coverage and failure-case coverage matter more.

Compare normalized intended operations, not payload byte size. For the customer service, normalize both paths into something like {operation: upsert_customer, customer_id, selected_fields, contract_version}. Store hashes or redacted summaries rather than entire sensitive payloads.

Build tests around event coverage. A proposed local acceptance matrix might require all selected customer event families, duplicate delivery, concurrent overlap, delayed fetch, fetch timeout, stale lease recovery, and rollback. Do not label those thresholds “Stripe requirements.” Stripe’s 24–48-hour suggestion is vendor guidance; your release gate should be tied to the cases your contract says must work.

These are integration tests, not just request examples. Refonte’s API testing foundations can support general test discipline, but concurrency, crashes, replay, and provider correlation require purpose-built harnesses beyond a basic collection.

The comparison record should preserve enough context to explain a mismatch later: the snapshot event ID, thin event ID, snapshot_event value when present, related-resource ID, observation timestamps, normalized operation, contract version, fetch result category, and final classification. Do not store complete customer objects simply because they are convenient. The goal is reproducibility without turning the shadow database into a second uncontrolled store of customer data.

For QA, a useful local rule is that every accepted divergence must map to a named semantic rule. “Different because thin is different” is not a rule. “Snapshot captured event-era name; thin fetched a later name; synchronization contract is latest-state convergence; terminal customer projection matches after replay” is a rule that a reviewer can test.

Conversely, a thin handler choosing delete_customer while the snapshot path chooses upsert_customer under the same business state is an unexplained behavioral divergence and blocks writes.

Also test asymmetry. Delay the snapshot worker while thin runs immediately, then reverse the delay. Drop the first fetch response, duplicate both deliveries, restart the worker pool during an active lease, and replay the completed event. These are proposed fault injections, not claims about Stripe behavior. Their purpose is to prove that correctness comes from the shared contract and ledger rather than from whichever handler happens to win a race.

Plan retries and replay by API and destination

Retry and replay are not one feature. Stripe documents automatic webhook delivery, Dashboard resend, command-line interface (CLI) resend, and v1 Events listing with different windows and semantics. These limits should not be copied onto an unverified private-preview path by analogy.

Automatic delivery retries and manual resends

For ordinary webhook delivery, Stripe documents live-mode automatic attempts for up to three days with exponential backoff; sandbox deliveries are retried three times over a few hours. Dashboard resend works for up to 15 days after event creation, while the CLI resend command works for up to 30 days. Stripe also states that a manual resend does not cancel existing automatic retry behavior.

Stripe does not guarantee event delivery order and warns that snapshot created timestamps can collide, so do not use timestamps as unique identities or a total ordering mechanism.

Recovery listing and the local completion record

Stripe’s undelivered-event guide says the v1 Events list used there returns events from the last 30 days, and delivery_success=false means an event was unsuccessfully delivered to at least one webhook endpoint. It also warns that a manual recovery script can run while automatic retries continue.

That provider-side filter is not proof that your business operation is unfinished. Conversely, a delivered status or 2xx is not proof that the business operation committed. Stripe describes 200 as successful delivery to the endpoint; local completion is your concern.

During replay, first resolve the logical key, then inspect the ledger. completed means acknowledge/skip unless reconciliation shows corruption. claimed with an active lease means defer. An expired claim is eligible for recovery. failed_retryable can be retried under policy. Unknown or ambiguous external effects require reconciliation, not blind execution.

Observe fetch dependencies and migration failure modes

Thin processing adds an explicit dependency on fetching details when the notification is insufficient. Stripe’s migration guide tells teams to measure fetch latency and error rates in shadow mode, while the event-destination overview describes fetching a complete event or related resource for more data.

That dependency must appear in capacity planning and incident response. A thin route can verify perfectly yet still fail to produce business work because the event/resource fetch is throttled, times out, returns an unsupported shape, or cannot be retried durably.

Log identifiers, states, durations, and redacted operation summaries. Do not log signing secrets, API keys, or full sensitive customer payloads merely to make shadow comparison convenient. Stripe itself recommends limiting event types and processing asynchronously, which also reduces unnecessary work under bursty delivery.

A readiness review should show the extra fetch call as an owned dependency with timeout, retry, circuit-breaking or backpressure behavior appropriate to your platform. “The payload is smaller” is not a substitute for that dependency model.

Rehearse cutover and reversal without erasing history

Cutover is a write-authority decision, not a destination-creation event. Stripe’s migration guide proposes shadowing, then a short overlap, then disabling the snapshot destination before eventual deletion. It also says that if something looks wrong, disable thin writes and use the snapshot handler as the point of reference.

The safest local rule is simpler: at every moment, know which path is authorized to create the business effect. Dual writes are acceptable only if the shared ledger and effect design have already proven that overlapping handlers cannot produce duplicate or permanently skipped work.

Stripe’s event-destination page says a destination can be disabled and later re-enabled; disabling stops event sending, while re-enabling resumes it. Its webhook retry documentation also notes retry behavior around disabled destinations, so rehearse your exact sequence rather than assuming disablement is equivalent to deletion.

Rollback must preserve the correlation and completion history accumulated during dual delivery. Otherwise the restored snapshot handler can no longer tell which logical events the thin path completed.

Rollback checklist: thin writes off; snapshot authority confirmed; accepted thin work classified; stale leases recovered; completed rows retained; ambiguous external effects reconciled; destination deletion deferred until the rollback window is closed.

Approve migration through a complete evidence pack

Approval should be evidence-based and owner-signed. A passing happy-path webhook is not enough. The pack should prove eligibility, identity, semantics, durability, replay, observability, and reversal for the exact account, event families, SDK, and preview API version tested.

A proposed rollout threshold might say “all selected event families observed at least once, all injected failure cases pass, no unexplained divergence remains, and the rollback rehearsal is complete.” Those are local gates, not Stripe guarantees. Stripe’s own guide recommends migrating event type by event type and avoiding indefinite dual-handler operation.

Keep “remain on snapshots” as a legitimate outcome. Private-preview access can be incomplete, an event family can be unsupported, or the extra fetch dependency can fail your reliability budget. A migration is successful only if it improves the operating model without weakening recovery.

For governance outside the Stripe-specific mechanics, Refonte’s production API management article can support broader ownership and lifecycle discussions.

Make ownership explicit before pilot approval. The integration owner should maintain the Stripe account, destination, event-family and preview-version inventory. The platform owner should own durable acceptance, queue/worker capacity, leases, retries, and database recovery. The application owner should define the business operation and what “completed” means.

QA should own the fixture catalog, concurrency schedule, crash points, shadow classifications, and evidence that expected failures were actually injected. Operations should own cutover, rollback, replay authorization, and reconciliation of ambiguous work.

That separation matters because the dangerous failures cross team boundaries. A missing snapshot_event may look like an application parsing bug but actually be an enrollment/version problem. A 500 during resource fetch may be transport-transient but becomes a data-loss defect if the worker has no durable retry.

A completed local row may still be insufficient if an external operation timed out after the remote provider committed it. Approval should therefore identify the person or role who can decide each ambiguity, not merely the team that receives the alert.

As a proposed operating cadence, review the evidence pack before enabling any new event family, after any preview/API-version change, after changing the processing-state schema, and before deleting the snapshot destination. The cadence is local policy; the important property is that changes affecting identity, semantics, or recovery reopen the relevant proof rather than inheriting a stale approval.

Build an integration-reliability portfolio

Turn the migration into reviewable engineering artifacts rather than a one-off code branch. Package the event contract, preview/version record, synthetic fixtures, state-transition model, failure-injection results, shadow-difference classifications, replay runbook, cutover plan, and rollback memo. That collection makes the reasoning auditable even if the preview changes later.

A concise reviewer score can use five dimensions: identity, semantics, durability, recoverability, and reversibility. “Pass” means there is evidence, not that the design sounds plausible.

For developers building those foundations, Refonte Learning’s APIs Developer Program lists REST, GraphQL, authentication and authorization, database integration, API testing and documentation, error handling and logging, versioning and deprecation, microservices, performance, and API security; the live page states three months at 10–12 hours per week, recommends basic programming knowledge, and lists working toward a bachelor’s or higher-level degree as an admission prerequisite. It does not verify Stripe thin/snapshot coverage, preview enrollment, or payments-specific certification, so use it for the underlying API engineering skills rather than assuming vendor-specific curriculum.

Answer the questions before retiring the old handler

Are Stripe API v1 thin events generally available? No. At the research cutoff of September 15, 2026, Stripe’s event-destination documentation describes thin events for API v1 resources as private preview. API v2 thin-event support is a separate, established path. Eligibility must be verified for the target account.

Does every thin event have snapshot_event? Do not assume so. The migration guide describes snapshot_event for interoperability thin events produced alongside snapshot events during this preview migration. Treat absence as either expected for a non-interop event or a stop condition when your tested contract requires correlation.

Does a 2xx prove processing completed? It proves successful webhook delivery to the endpoint in Stripe’s delivery model, not that your downstream transaction or remote side effect committed. That distinction follows directly from Stripe’s recommendation to acknowledge quickly and process asynchronously. Your durable ledger must hold the completion fact.

Do outbound idempotency keys replace the event ledger? No. Stripe’s request-idempotency mechanism protects retries of API requests and may prune keys after they are at least 24 hours old. It does not tell your consumer whether an inbound logical event has passed through receipt, claim, effect, reconciliation, and completion.

What must survive rollback? At minimum: transport receipts, logical-event correlation, processing state, completion evidence, outbound operation identifiers where applicable, and divergence/recovery records. The snapshot path can become authoritative again, but it must consult the same processing history used during overlap.

Retire the old handler only when that artifact is complete. Until then, the correct state is not “half migrated.” It is “snapshot-authoritative, thin candidate under evidence collection.”