ClearForge: synchronizing subscription state
A walkthrough of Stripe events and business subscription records in the ClearForge repository.
View source code ↗Problem
The repository includes a customer-request product for local businesses. Its billing integration updates business access and usage limits from Stripe subscription events.
Constraints
Billing state arrives through multiple event types, including checkout completion, subscription updates, cancellation, and paid invoices. Incoming webhook payloads must be authenticated.
Architecture
The webhook reads the raw request body and verifies the Stripe signature before handling events. Checkout completion associates a customer and subscription with a business. Subscription updates synchronize status, plan, and request limits; deletion marks the subscription cancelled; paid invoices reset usage.
Technical tradeoff
One route dispatches by event type and updates the business record. This keeps the mapping between events and application state explicit. It does not by itself provide an event ledger or establish event-ordering guarantees. This is a code interpretation, not a recollection of the original design decision.
Failure modes & verification
A review scenario is replaying or reordering subscription events: the inspected route has no explicit processed-event ledger, and active subscription updates reset the usage counter. The effect should be tested against the intended billing rules. This is not a reported outage or a claim that idempotency is implemented.
Next iteration
Proposed next iteration: define replay and ordering behavior, record processed event IDs, scope usage resets to the intended billing period, and check database update results before acknowledging success.
Evidence & metrics
No verified event volume, delivery success rate, or billing latency is published. Source links show the current behavior directly.