Similar to
Guide
Configure webhook endpoints to receive real-time event notifications for payment status changes, subscription updates, and refund outcomes.
payments,
the
subscription updates
Webhook
sends merchants asynchronous notifications when a subscription changes.
The webhook structure is similar to the subscription status method, but with a callback_type parameter in the response object, indicating the nature of the subscription event that triggered the notification.
Subscription events provide detailed context for each subscription stage, giving merchants visibility into the full subscription lifecycle. They support improved subscription management and analysis.
Merchants can track subscription states more effectively and make data-driven decisions to optimize their subscription-based revenue.
| Value | Description |
|---|---|
| create | A new subscription is created with a pending status, awaiting payment. |
| expire | A pending subscription expires during its creation process, for example, due to unsuccessful payment. |
| payment_attempt | An additional invoice representing a payment attempt was created while the subscription was in the pending status. |
| active | A notification is received about a successful payment, and the subscription status is updated to active. |
| renew | A new billing period for an active subscription begins, meaning that a recurring payment has succeeded. |
| recurring | The recurring billing process is initiated, and an order has been sent to the payment gateway. |
| order_update | A recurring subscription order status changes to settled or voided. The initial order for a subscription is refunded, voided, or settled.
If the subscription has multiple invoices, this event is only sent for the most recent invoice at the time the order status changes. Webhooks for orders on older invoices are suppressed. To receive events for all order updates regardless of invoice status, Guide Subscribe for events so your integration can automatically trigger actions. subscribe to card_gate.order.updated and alt_gate.order.updated event types. |
| pause_schedule.create | A new pause schedule is created for an active subscription. |
| pause_schedule.update | The existing pause schedule for an active or paused subscription is updated. |
| pause | An active subscription is automatically paused according to the pause schedule. |
| resume | A paused subscription is automatically resumed after the pause period ends. Or an active paused subscription is manually resumed via the API. |
| pause_schedule | A pause schedule for an active subscription is deleted. |
| redemption | A recurring subscription order is declined, and the subscription moves to the redemption period. |
| retry | An order is created for a subscription in the redemption period, attempting to retry the payment. |
| scheduled_for_retry | The next retry date is scheduled or updated for a subscription in the redemption period after the previous retry attempt was declined. |
| restore | A cancelled subscription, or one scheduled for cancellation while still in active status, is restored via the API or through mass operations. |
| switch_product | An active subscription is moved to a different product. This event also fires when an upgrade charge fails and the subscription reverts to the original product. |
| scheduled_for_cancellation | An active subscription is scheduled to be cancelled at the end of the current billing period by the scheduler after a soft cancel. |
| cancel | An active subscription can be force-cancelled for various reasons, such as by ID, by the customer via API, by mass operation, fraud or dispute events, stop declines, or other business cases. This can also involve a two-step cancellation, where a subscription previously scheduled for cancellation is officially cancelled at the end of its billing period. |
To start receiving webhooks, you need to subscribe to the Subscription updates event. If you do not have the new extended statuses activated, the following webhooks cannot be received:
- create
- expire
- payment_attempt
- Go to Developers > select the API v2 version Channels.
- Find the channel and click on it.
- In the Webhook endpoints section, select +Add an endpoint.
- In the appeared form:
- Select Subscription updates from the dropdown list.
- Specify URL.
- Click on Add to save changes and start receiving subscription events.