Use webhooks to receive real-time updates from the Subscription Engine. We send an event to your endpoint whenever an order, subscription, or refund changes state.

​
Event types

We send HTTPS notifications to your server as events occur so you can react immediately. Each event belongs to one of four types:
  • Subscription events: Lifecycle changes such as renewing, pausing, resuming. Find the full list below.
{
    "event_id": "018522bc-905a-4124-a955-37db2a731ab2",
    "event_timestamp": "2025-09-25T12:11:17.381627",
    "event_type": "subscription",
    "external_id": "231944a8-d819-4544-9088-6f0098d741d3",
    "is_livemode": false,
    "subscription": {
    "available_actions": [
    "pause",
    "defer",
    "disable_autorenew",
    "create_discount"
    ],
    "current_period_ends_at": "2025-10-02T12:11:17.378076",
    "current_period_starts_at": "2025-09-25T12:11:17.378076",
    "initial_order_metadata": {
    "test_client_metadata": "xxxxx"
},
    "is_active": true,
    "next_check_at": "2025-10-02T10:11:17.378076",
    "price_point": {
    "currency": {
    "code": "USD",
    "minor_units": 2,
    "symbol": "$",
    "title": "US Dollar"
},
    "features": [
{
    "ident": "premium"
}
    ],
    "ident": "another_premium_lifetime_99_99",
    "intro_free_trial_period": null,
    "intro_free_trial_period_duration": null,
    "intro_paid_trial_period": 1,
    "intro_paid_trial_period_duration": "weeks",
    "intro_paid_trial_price": "1",
    "intro_type": "paid_trial",
    "lifetime_price": null,
    "next_period": 1,
    "next_period_duration": "months",
    "next_price": "9.99"
},
    "started_at": "2025-09-25T12:11:17.378076",
    "status": [
    "INTRO"
    ],
    "subs_id": "2d36a705-133f-491d-8206-532fca8928c8"
},
    "subtype": "starting_trial"
}
  • Order events: Sent when a payment reaches the Settled status. Optionally, Declined events can be sent (disabled by default).
{
    "event_id": "be9375d7-a6b9-4411-975f-ae7c8bc16949",
    "event_timestamp": "2025-09-25T12:11:18.681057",
    "event_type": "order",
    "order": {
    "amount": "1",
    "currency_code": "USD",
    "external_id": "231944a8-d819-4544-9088-6f0098d741d3",
    "initial_order_metadata": {
    "test_client_metadata": "xxxxx"
},
    "oneoff_id": null,
    "order_id": "71490129-fbfd-487d-91ed-1de5d88dd07f",
    "subs_id": "2d36a705-133f-491d-8206-532fca8928c8",
    "user_uuid": "e7a66d27-4f56-47e6-9bf7-82dc754a4a85"
},
    "subtype": "settled"
}
  • Lifetime access / one-off purchase events: For one-time purchases, only two events are possible:
    • Granted — access granted
    • Revoked — access revoked
  • Refund events: Sent when a refund is completed.
Every event includes a unique event_id. Use this ID for idempotency—if you’ve already processed an event with the same event_id, ignore the duplicate.

​
Subscription events

These events describe changes across the subscription lifecycle.
EventDescription
STARTING_TRIALStart of the trial period
CONVERSIONConversion from trial to paid subscription
RENEWINGSubscription renewal (regular charge)
UNSUBSCRIPTIONUser cancels subscription (auto-renewal turned off)
PAUSINGSubscription is paused
DEFERRINGPostponement of next charge date (deferred subscription)
RESUMINGResuming a paused subscription
RECOVERING_AUTORENEWRestoring auto-renewal after failure
EXPIRATIONSubscription expiration
UNKNOWNUnknown or unclassified event
START_GRACEStart of grace period after a failed charge
START_RETRYStart of retry attempts without a grace period
FINISH_GRACEEnd of grace period
RECOVERINGRecovery from grace/retry state

​
Webhook retries

If delivery fails (for example, your server is unavailable or returns a non-2xx status), we retry up to 6 times with exponential backoff. Intervals are in seconds, with the last wait about 72 hours (configurable per merchant): 
[8, 64, 512, 4096, 32768, 262144]

Retries continue until success or the maximum number of attempts is reached.

<Info>Delivery is considered successful when your endpoint returns HTTP 2xx.</Info>