Webhook-Driven State

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

1. preserve the exact raw request body
2. verify the webhook signature and timestamp
3. deduplicate by event ID
4. apply the state transition only after verification succeeds

This keeps fulfillment and entitlements tied to a trustworthy, replay-safe event stream.

Related pages