Subscription state changes
Choose published lifecycle events and reconcile subscription access.
The public webhook specification currently lists subscription.created,
subscription.activated, subscription.canceled, subscription.renewed,
subscription.paused, subscription.resumed, and subscription.plan_changed.
It does not publish a subscription.updated webhook contract.
subscription.paused and subscription.resumed announce an immediate pause and
a resume made through the API or the dashboard. A resume the customer makes in the
portal, and a pause scheduled for the end of the period taking effect, are not
announced, so reconcile from the subscription's current status.
subscription.plan_changed announces a move to another price made through the API or
the dashboard. Nothing is charged at that moment: the proration is billed or credited
on the next renewal invoice. Fetch the subscription for its current price and amount.
Choose a published event
Use the subscription event catalogue for schemas and examples. Do not subscribe to an undocumented generic update event on the basis of an older guide.
Reconcile access
A subscription lifecycle notification is not automatically proof of payment. Fetch the
current subscription through the API and inspect its status and effective period or
cancellation dates before granting or revoking access. Use invoice.paid for an
invoice-based fulfilment workflow; avoid applying the same business effect from two events.
Verify the raw signature, accept work into a durable inbox, and use a business
idempotency key. Do not rely on event order or assume previous_attributes is present.
Owner: david · Reviewed 10 Oct 2026 · Next review 30 Oct 2026