Webhooks & reconciliation
Subscribe to subscription events to react to lifecycle changes and reconcile them against your own records. See Webhooks for endpoint setup, the signed-envelope format, signature verification, and retries; this page covers the subscription topics and how to reconcile them.
Topics
| Topic | Fires when |
|---|---|
subscription.assigned | Fired when a subscription is assigned to a customer (may be future-dated / upcoming). |
subscription.started | Fired when a subscription becomes active — grant entitlement/access on this event, not on assigned. |
subscription.updated | Fired when a config property changes without a structural transition (e.g. name, payment method, billing direction). |
subscription.transitioned | Fired on a structural change: plan replace, product edit, billing cadence change, or realign. |
subscription.paused | Fired when a subscription is paused. |
subscription.resumed | Fired when a subscription resumes from a pause. |
subscription.trial_ended | Fired when a subscription trial ends and normal billing begins (the sub stays active). |
subscription.cancellation_scheduled | Fired when a future cancellation is scheduled for a subscription (still active until then). |
subscription.cancellation_cleared | Fired when a previously scheduled cancellation is cleared. |
subscription.churned | Fired when a subscription is cancelled/finalized — revoke entitlement on this event. |
subscription.billed | Fired once per (child) subscription when a billing run produces its invoice. |
subscription.payment_succeeded | Fired when a card charge for the subscription clears — the success pair of the charge_failed error signal. |
subscription.error | Fired when a delivery/processing problem occurs for a subscription (e.g. undeliverable recipient). |
subscription.error
The subscription.error topic reports a billing problem rather than a lifecycle
change.
The errorType field discriminates which problem occurred — it is one of:
errorType | Meaning |
|---|---|
recipient_undeliverable | A document recipient for the subscription is undeliverable (e.g. the email hard-bounced); the document was not delivered. |
charge_failed | A card charge (first or recurring) for the subscription failed; the subscription is moved to AWAITING_PAYMENT so you can gate access. The raw provider decline is not exposed on the payload. |
Reconcile on the stable id
Every subscription.* event carries the stable id as data.subscriptionId, plus
data.partnerReferenceId and a diagnostics-only data.versionId. Reconcile on
subscriptionId or partnerReferenceId, never versionId — the version id
changes on every structural change (see
Data model).
partnerReferenceId is the clientReferenceId you pass when binding an
embedded checkout — your join key
for matching a subscription to your own order.
Recover a lost event
If a delivery is lost, recover the join over the API by your own reference:
Code