Separate product telemetry from billing facts
Product telemetry describes user behavior; billing systems establish their own transaction and subscription facts. Keep those authorities separate, link events through stable business identifiers, and apply duplicates, reversals, and out-of-order deliveries through a versioned projection with reconciliation.
Inside this article 5 sections +
A customer clicks Cancel subscription. Product analytics records the click immediately, but the billing system may reject the request, schedule cancellation at the end of the period, or complete it later. Treating the click as an authoritative cancellation can revoke access or send a misleading message.
Separate observations from business facts. Telemetry explains what users attempted and how they moved through the product. Application and billing records establish accepted commands, subscription state, invoices, payments, and reversals under their respective contracts.
Assign an owner to every fact
Write an event dictionary that names the producing authority, business identifier, meaning, and consumers. A product event such as cancellation_clicked belongs to interaction analysis. A command-accepted record belongs to the application's workflow. A billing subscription update establishes the provider's current state, which the application then maps to its entitlement policy.
Keep scheduled and effective state separate. A subscription marked to cancel at period end may remain entitled until that boundary under the product's rules. A dashboard counting cancellation requests answers a different question from one counting subscriptions whose service ended.
Use a correlation identifier to connect the journey without pretending every system shares one event ID. Preserve the source event ID, object ID, command ID, and local projection version where relevant. They serve different deduplication and diagnostic purposes.
Do not infer business order from arrival order
Webhook delivery can be duplicated and out of generation order. Stripe explicitly documents those possibilities. A later-arriving event is not necessarily the newest business state, and timestamp precision may be insufficient to order distinct events.
Deduplicate transport deliveries by source event ID, then apply business semantics to the affected object. Where an event is a notification of changed state, fetching the current authoritative object can be appropriate. Where the event represents an immutable transaction, preserve it as a fact with its relationship to other transactions.
Do not use one rule for every event type. Replacing a subscription projection with current state differs from appending a confirmed payment to an immutable ledger. Document the projection strategy for each class and test replay under that strategy.
Represent reversals as linked facts
A reversal should refer to the original operation and preserve its own identity. Deleting the original row to make a total look correct removes the history needed to explain what occurred. The following invented example uses one currency and confirmed movement amounts solely to illustrate event application.
| Business fact | Source identity | Amount | Application |
|---|---|---|---|
| Payment confirmed | payment-P1 | +30,000 | Apply once |
| Refund confirmed, refers to P1 | refund-R1 | −5,000 | Apply once with original reference |
| Same refund delivered again | refund-R1 | −5,000 payload | Ignore duplicate application |
| Net confirmed movement | P1 and R1 | 25,000 | Keep both original facts |
A provider may emit several event types about the same underlying operation. Transport deduplication alone will not prevent counting that operation twice if the projection treats each type as a new payment. Define the canonical business identity and which event establishes the fact.
Preserve pending, failed, and confirmed states according to the source contract. An initiated refund is not necessarily a completed movement. Keep the product experience and reporting labels aligned with the state actually established.
Reconcile projections against authoritative records
Store an inbox or equivalent durable receipt record before acknowledging events, then process them into the appropriate projection. Retain failed applications for retry or investigation. A successful webhook acknowledgement should not be the only evidence that the business state was updated.
Run periodic reconciliation using stable object and operation identifiers. Compare subscription states, known invoices, or confirmed movements at a defined boundary. Reconciliation repairs missed delivery and projection defects; it should not blindly overwrite local policy fields owned by the application.
Separate discrepancy categories: event missing, event received but not applied, mapping unresolved, stale projection, or legitimate policy difference. For example, billing may show an active subscription while product access is temporarily suspended for an unrelated authorized reason. The systems disagree only if the contract says they should match on that field.
Give analytics and messaging the right event
Analytics can retain the full journey to measure intent, friction, and completion. Entitlement consumers should use authoritative state and explicit policy. Customer messaging should wait for the fact its wording promises, such as cancellation scheduled rather than cancellation clicked.
Test duplicate webhook delivery, reordered subscription updates, a partial refund, a failed refund, a missing account mapping, and a replay after a consumer restart. Assert both the final projection and the retained lineage. A correct final total can still conceal a duplicated message or an incorrect access transition.
Read lifecycle event contracts for shared meanings and outbox crash tests for durable publication. Our architecture consulting services help connect those mechanisms to clear event ownership.