Subscription Webhooks

Webhooks may be sent more than once—add deduplication logic to prevent duplicate events.

The webhook examples on this page assume bank or card settlement. The signature field and any non-zero gasFees only appear on advanced stablecoin settlement paths.

✅ Event Types

Subscription webhooks fall into two categories:

Subscription category — lifecycle events unique to subscriptions (created, canceled, expired, failure)
Purchase category — standard payment events that also fire on subscription billing cycles, and include a subscription object in the payload

Event Type	Category	Description
Subscription Created	Subscription	A subscription was purchased and activated for the first time.
Subscription Canceled	Subscription	A subscription was canceled by the customer or merchant. Includes a `reason` field.
Subscription Expired	Subscription	The subscription can no longer be renewed (e.g. plan deactivated or max duration reached).
Subscription Failure	Subscription	A renewal payment failed, preventing the subscription from being created or renewed.
Settled	Purchase	A subscription billing payment completed successfully. Includes a `subscription` object.
Card Payment Authorized	Purchase	A subscription renewal card was authorized but not yet captured. Includes a `subscription` object.
Card Payment Declined	Purchase	A subscription renewal card was declined by the issuing bank.

Sample Webhook Payloads

Subscription Lifecycle Events

These events use the Subscription category and contain subscription-specific data.

Subscription Created

1 // Sent when a customer pays for a subscription for the first time
2 {
3   "eventType": "Subscription Created",
4   "category": "Subscription",
5   "created": "2025-04-28T20:28:08.289Z",
6   "data": {
7     "planCode": "music_access",
8     "planName": "creator1234",
9     "subscriptionId": "680fe4d832ddccc1ee91885e",
10     "customerId": "cust_abc123",
11     "amount": {
12       "cents": 500,
13       "currency": "USD"
14     },
15     "interval": "Monthly",
16     "fundingMethod": "Card",
17     "webhookInfo": {
18       "item": "sword"
19     }
20   }
21 }

Subscription Canceled

1 // Sent when a customer or merchant cancels a subscription
2 {
3   "eventType": "Subscription Canceled",
4   "category": "Subscription",
5   "created": "2025-04-28T20:33:05.322Z",
6   "data": {
7     "planCode": "music_access",
8     "planName": "creator1234",
9     "subscriptionId": "67d07938a899c293e0ae2147",
10     "customerId": "cust_abc123",
11     "amount": {
12       "cents": 500,
13       "currency": "USD"
14     },
15     "interval": "Monthly",
16     "fundingMethod": "Card",
17     "webhookInfo": {
18       "item": "sword"
19     },
20     "reason": "Customer has canceled subscription"
21   }
22 }

Subscription Expired

1 // Sent when a subscription can no longer be renewed
2 {
3   "eventType": "Subscription Expired",
4   "category": "Subscription",
5   "created": "2025-04-28T20:35:00.000Z",
6   "data": {
7     "planCode": "music_access",
8     "planName": "creator1234",
9     "subscriptionId": "67d07938a899c293e0ae2147",
10     "customerId": "cust_abc123",
11     "amount": {
12       "cents": 500,
13       "currency": "USD"
14     },
15     "interval": "Monthly",
16     "fundingMethod": "Card",
17     "webhookInfo": {
18       "item": "sword"
19     },
20     "reason": "Subscription has expired"
21   }
22 }

Subscription Failure

1 // Sent when a renewal payment fails and the subscription cannot be renewed
2 {
3   "eventType": "Subscription Failure",
4   "category": "Subscription",
5   "created": "2025-04-28T20:36:00.000Z",
6   "data": {
7     "planCode": "music_access",
8     "planName": "creator1234",
9     "subscriptionId": "67d07938a899c293e0ae2147",
10     "customerId": "cust_abc123",
11     "amount": {
12       "cents": 500,
13       "currency": "USD"
14     },
15     "interval": "Monthly",
16     "fundingMethod": "Card",
17     "webhookInfo": {
18       "item": "sword"
19     }
20   }
21 }

Subscription Payment Events

These events use the Purchase category and include a subscription object containing the full subscription and plan details.

Settled

1 // Sent when a subscription billing payment completes; funds are in your settlement wallet
2 {
3   "eventType": "Settled",
4   "category": "Purchase",
5   "created": "2025-04-28T20:28:10.894Z",
6   "data": {
7     "id": "db746ccf-6dce-4019-b34b-b35a957cb5aa",
8     "signature": "db746ccf6dce4019b34bb35a957cb5aa", // settlement reference; only present on advanced stablecoin settlement paths
9     "webhookInfo": {
10       "item": "sword"
11     },
12     "subtotal": {
13       "cents": 500,
14       "currency": "USD"
15     },
16     "fees": {
17       "cents": 46,
18       "currency": "USD"
19     },
20     // gasFees is only non-zero on advanced stablecoin settlement paths; otherwise 0
21     "gasFees": {
22       "cents": 0,
23       "currency": "USD"
24     },
25     "chargebackProtectionFees": {
26       "cents": 0,
27       "currency": "USD"
28     },
29     "total": {
30       "cents": 546,
31       "currency": "USD"
32     },
33     "subscription": {
34       "_id": "680fe4d832ddccc1ee91885e",
35       "customer": "66ce47a1e487adc8f4ab0d46",
36       "merchant": "66311727a26b3cb28faaf97d",
37       "plan": {
38         "amount": {
39           "cents": 500,
40           "currency": "USD"
41         },
42         "_id": "67bf86d03716ba82ce5cd096",
43         "merchant": "66311727a26b3cb28faaf97d",
44         "name": "creator1234",
45         "code": "music_access",
46         "interval": "Monthly",
47         "duration": 12,
48         "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
49         "active": true,
50         "__v": 0
51       },
52       "cardProcessor": "mock",
53       "reference": "f008bb21-f6a1-4947-b271-90e78638f379",
54       "nextPaymentAt": "2025-05-28T20:28:08.164Z",
55       "status": "Active",
56       "webhookInfo": {
57         "item": "sword"
58       },
59       "createdAt": "2025-04-28T20:28:08.169Z",
60       "updatedAt": "2025-04-28T20:28:08.169Z",
61       "__v": 0
62     },
63     "merchantId": "testtest",
64     "customerId": "cust_abc123",
65     "rawCustomerId": "cust_abc123"
66   }
67 }

Card Payment Authorized

1 // Sent when a subscription renewal card is authorized but not yet captured
2 {
3   "eventType": "Card Payment Authorized",
4   "category": "Purchase",
5   "created": "2025-04-28T20:31:19.543Z",
6   "data": {
7     "webhookInfo": {
8       "item": "sword"
9     },
10     "subtotal": {
11       "cents": 500,
12       "currency": "USD"
13     },
14     "fees": {
15       "cents": 46,
16       "currency": "USD"
17     },
18     "gasFees": {
19       "cents": 0,
20       "currency": "USD"
21     },
22     "chargebackProtectionFees": {
23       "cents": 0,
24       "currency": "USD"
25     },
26     "total": {
27       "cents": 546,
28       "currency": "USD"
29     },
30     "merchantId": "testtest",
31     "id": "39ffc711-8023-46cf-b6ad-5dac81afec88",
32     "subscription": {
33       "_id": "67d07938a899c293e0ae2147",
34       "customer": "67d07935a899c293e0ae2132",
35       "merchant": "66311727a26b3cb28faaf97d",
36       "plan": {
37         "amount": {
38           "cents": 500,
39           "currency": "USD"
40         },
41         "_id": "67bf86d03716ba82ce5cd096",
42         "merchant": "66311727a26b3cb28faaf97d",
43         "name": "creator1234",
44         "code": "music_access",
45         "interval": "Monthly",
46         "duration": 12,
47         "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
48         "active": true,
49         "__v": 0
50       },
51       "cardProcessor": "mock",
52       "reference": "148a2d77-c025-4c48-bccb-f8474ffcf903",
53       "nextPaymentAt": "2025-05-11T17:56:08.261Z",
54       "status": "Active",
55       "webhookInfo": {
56         "item": "sword"
57       },
58       "createdAt": "2025-03-11T17:56:08.262Z",
59       "updatedAt": "2025-04-11T20:30:00.146Z",
60       "__v": 0
61     },
62     "customerId": "cust_abc123",
63     "rawCustomerId": "cust_abc123"
64   }
65 }

Card Payment Declined

1 // Sent when a subscription renewal card is declined by the issuing bank
2 {
3   "eventType": "Card Payment Declined",
4   "category": "Purchase",
5   "created": "2025-04-28T20:21:50.163Z",
6   "data": {
7     "webhookInfo": {
8       "item": "sword"
9     },
10     "subtotal": {
11       "cents": 500,
12       "currency": "USD"
13     },
14     "fees": {
15       "cents": 46,
16       "currency": "USD"
17     },
18     "gasFees": {
19       "cents": 0,
20       "currency": "USD"
21     },
22     "chargebackProtectionFees": {
23       "cents": 0,
24       "currency": "USD"
25     },
26     "total": {
27       "cents": 546,
28       "currency": "USD"
29     },
30     "merchantId": "testtest",
31     "id": "bce7ca59-4bcc-43c3-95f1-51f2858b0bd2",
32     "declineCode": "59",
33     "declineDescription": "The transaction is suspected of fraud.",
34     "customerId": "cust_abc123",
35     "rawCustomerId": "cust_abc123"
36   }
37 }

Schema

Subscription Lifecycle Event Schema

Applies to: Subscription Created, Subscription Canceled, Subscription Expired, Subscription Failure

Schema

1 {
2   "eventType": "string",
3   "category": "Subscription",
4   "created": "string (ISO 8601)",
5   "data": {
6     "planCode": "string",
7     "planName": "string",
8     "subscriptionId": "string",
9     "customerId": "string",
10     "amount": { "cents": "number", "currency": "string" },
11     "interval": "string (Monthly | Yearly | Weekly | Daily)",
12     "fundingMethod": "string (Card)",
13     "webhookInfo": { "key": "value" },
14     "reason": "string (optional — present on Canceled and Expired events)"
15   }
16 }

Subscription Payment Event Schema

Applies to: Settled, Card Payment Authorized, Card Payment Declined (when triggered by a subscription billing cycle)

Schema

1 {
2   "eventType": "string",
3   "category": "Purchase",
4   "created": "string (ISO 8601)",
5   "data": {
6     "id": "string",
7     "signature": "string (present on Settled)",
8     "webhookInfo": { "key": "value" },
9     "subtotal": { "cents": "number", "currency": "string" },
10     "fees": { "cents": "number", "currency": "string" },
11     "gasFees": { "cents": "number", "currency": "string" },
12     "chargebackProtectionFees": { "cents": "number", "currency": "string" },
13     "total": { "cents": "number", "currency": "string" },
14     "merchantId": "string",
15     "customerId": "string",
16     "rawCustomerId": "string",
17     "declineCode": "string (present on Card Payment Declined)",
18     "declineDescription": "string (present on Card Payment Declined)",
19     "subscription": {
20       "_id": "string",
21       "status": "string (Active | Canceled | Expired)",
22       "nextPaymentAt": "string (ISO 8601)",
23       "plan": {
24         "code": "string",
25         "name": "string",
26         "interval": "string",
27         "duration": "number",
28         "amount": { "cents": "number", "currency": "string" }
29       },
30       "webhookInfo": { "key": "value" }
31     }
32   }
33 }