Webhook-Driven State
Trust signed webhooks for durable payment state transitions
Invoice creation tells you that a payment can happen. Webhooks tell you that it did happen.
That distinction matters because payment settlement is asynchronous.
The model
Your app should treat signed webhook deliveries as the durable trigger for local state transitions such as:
- activating a subscription
- marking a checkout as paid
- granting entitlements
- closing out expired or canceled invoices
Polling public invoice status can help the client understand progress, but webhook delivery is the right place to finalize merchant-side state.
Why this pattern is safer
- settlement may happen after invoice creation
- delivery may be retried, so you need deduplication
- signed webhooks let your backend verify authenticity before mutating local state
- your business logic stays anchored to an explicit event boundary
The practical rule is: verify first, then mutate state.
What to do in your app
- preserve the exact raw request body
- verify the webhook signature and timestamp
- deduplicate by event ID
- apply the state transition only after verification succeeds
This keeps fulfillment and entitlements tied to a trustworthy, replay-safe event stream.