WebhooksEvents

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.

Receive and verify events.

Owner: david · Reviewed 10 Oct 2026 · Next review 30 Oct 2026

On this page