Skip to main content

Subscription webhooks

PaymentsAI dispatches webhook events for subscription lifecycle activity, the transactions those subscriptions generate, and related disputes and offsite payments. Subscribe to the events you need and react server-side rather than polling.

For the registration mechanism, payload schemas, and delivery guarantees, see Webhooks overview and Webhooks schemas.

All event names use hyphens (for example subscription-activated, not subscription.activated).

Subscription events​

EventWhen it fires
subscription-activatedThe subscription has moved to active — typically after the first payment succeeds.
subscription-renewedA scheduled renewal has been processed.
subscription-canceledThe subscription has been canceled (immediately or at a scheduled date).
subscription-churnedThe subscription has churned (final cancellation after retries exhausted, end of contracted term, or similar terminal state).
subscription-upgradedThe subscription has been upgraded to a higher-priced plan. See Upgrade and downgrade.
subscription-downgradedThe subscription has been downgraded to a lower-priced plan.
subscription-modifiedThe subscription has been modified (changes other than upgrade or downgrade).
subscription-items-changedThe line items on the subscription have changed.
subscription-reactivatedA scheduled cancellation has been reversed and the subscription continues. See Subscription reactivation.
subscription-trial-changedThe trial configuration on the subscription has changed.
subscription-trial-endedA trial period has ended.
subscription-trial-end-reminderDispatched ahead of trial end. See the dedicated reference page.
subscription-renewal-reminderDispatched 7 days before a scheduled renewal. See the dedicated reference page.

Transaction events​

EventWhen it fires
transaction-processedA transaction has been processed by the gateway. This is the standard "transaction completed" signal.
transaction-declinedA transaction has been declined. See the dedicated reference page. Fires for each declined attempt during subscription dunning.

Order and payment events​

EventWhen it fires
order-delinquency-reachedThe order (subscription) has reached delinquency — payment retries have exhausted and the customer is past due.
offsite-payment-completedThe customer has completed a payment on the offsite hosted form. See Hosted payment form.

Dispute events​

EventWhen it fires
dispute-createdA new dispute (chargeback or inquiry) has been opened on a transaction.
dispute-updatedAn existing dispute has been updated (status, evidence, deadline).
dispute-lostA dispute has been lost — funds have been debited from your account.
dispute-commentsA new comment has been added to a dispute thread.

See Dispute process for how to respond to disputes.

Dedicated webhook reference pages​

Three events have their own reference pages with full payload examples — these are the canonical source for the payload shape:

For the other events, register your endpoint and observe the delivered payloads to confirm the exact shape.

Webhook registration​

You register webhook endpoints with PaymentsAI and pick which events to receive via the eventTypes array. See Webhook setup for the registration flow, including HMAC signature verification.

Delivery guarantees​

From the Webhooks overview:

  • Out-of-order delivery — PaymentsAI does not guarantee event ordering. Your endpoint must handle events that arrive out of sequence.
  • At-least-once delivery — events may be delivered more than once. Use the deduplicationId on every payload to drop duplicates server-side.
  • Live and test mode — a single registered endpoint can receive both live and test mode events. Use the payload contents (and your own routing) to separate them.

Typical sequence — first subscription with inactive instrument​

For a subscription created against a new (inactive) payment instrument:

  1. The subscription is created in pending.
  2. The customer is redirected to the hosted payment form and completes the first payment.
  3. offsite-payment-completed fires when the customer finishes the hosted-form step.
  4. transaction-processed fires for the first payment.
  5. subscription-activated fires when the subscription moves to active.

From here, each renewal fires transaction-processed and subscription-renewed once the renewal charge succeeds.

For a subscription created against an already-active payment instrument, transaction-processed and subscription-activated follow creation without an intermediate hosted-form step.

Typical sequence — failed renewal and recovery​

  1. The scheduled renewal charge fails. PaymentsAI dispatches transaction-declined for the failed attempt.
  2. Dunning retries fire further transaction-declined events on each failed attempt.
  3. Either the renewal eventually succeeds (transaction-processed, subscription-renewed), or the retries are exhausted (order-delinquency-reached) and the subscription is canceled or churned (subscription-canceled or subscription-churned).

See Dunning and retries for what happens between the first failure and the final outcome.