Skip to main content

Provider webhooks

Provider webhook processing is the durable state transition layer for self-serve billing. For cloud users, this pipeline is operated by Vluna.

This guide explains what guarantees your application should rely on.

Prereqs​

Platform guarantees​

  • Duplicate provider events are deduplicated by provider event id.
  • Processing is idempotent for subscription, payment, and invoice updates.
  • Out-of-order and delayed events are tolerated through reconciliation-style updates.
  • Subscription updates and deletions are projected from provider subscription events.

What your product should do​

  • Treat checkout redirect completion as provisional.
  • Drive entitlement-sensitive UX from billing APIs after webhook processing.
  • Show recoverable pending states when provider confirmation is delayed.
  • Route conflicting self-serve changes to portal-based resolution.

Verify​

Simulate:

  • a duplicate webhook delivery
  • a delayed delivery

Confirm:

  • no duplicate grants/plan projections
  • no duplicate subscription transitions
  • eventual convergence to provider state

Next​