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

<th>
  Category
</th>

<th>
  Description
</th>

Subscription Created

<td>
  Subscription
</td>

<td>
  A subscription was purchased and activated for the first time.
</td>

Subscription Canceled

<td>
  Subscription
</td>

<td>
  A subscription was canceled by the customer or merchant. Includes a 

  `reason`

   field.
</td>

Subscription Expired

<td>
  Subscription
</td>

<td>
  The subscription can no longer be renewed (e.g. plan deactivated or max duration reached).
</td>

Subscription Failure

<td>
  Subscription
</td>

<td>
  A renewal payment failed, preventing the subscription from being created or renewed.
</td>

Settled

<td>
  Purchase
</td>

<td>
  A subscription billing payment completed successfully. Includes a 

  `subscription`

   object.
</td>

Card Payment Authorized

<td>
  Purchase
</td>

<td>
  A subscription renewal card was authorized but not yet captured. Includes a 

  `subscription`

   object.
</td>

Card Payment Declined

<td>
  Purchase
</td>

<td>
  A subscription renewal card was declined by the issuing bank.
</td>

Sample Webhook Payloads

Subscription Lifecycle Events

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

// Sent when a customer pays for a subscription for the first time
{
  "eventType": "Subscription Created",
  "category": "Subscription",
  "created": "2025-04-28T20:28:08.289Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "680fe4d832ddccc1ee91885e",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    }
  }
}

// Sent when a customer or merchant cancels a subscription
{
  "eventType": "Subscription Canceled",
  "category": "Subscription",
  "created": "2025-04-28T20:33:05.322Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    },
    "reason": "Customer has canceled subscription"
  }
}

// Sent when a subscription can no longer be renewed
{
  "eventType": "Subscription Expired",
  "category": "Subscription",
  "created": "2025-04-28T20:35:00.000Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    },
    "reason": "Subscription has expired"
  }
}

// Sent when a renewal payment fails and the subscription cannot be renewed
{
  "eventType": "Subscription Failure",
  "category": "Subscription",
  "created": "2025-04-28T20:36:00.000Z",
  "data": {
    "planCode": "music_access",
    "planName": "creator1234",
    "subscriptionId": "67d07938a899c293e0ae2147",
    "customerId": "cust_abc123",
    "amount": {
      "cents": 500,
      "currency": "USD"
    },
    "interval": "Monthly",
    "fundingMethod": "Card",
    "webhookInfo": {
      "item": "sword"
    }
  }
}

Subscription Payment Events

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

// Sent when a subscription billing payment completes; funds are in your settlement wallet
{
  "eventType": "Settled",
  "category": "Purchase",
  "created": "2025-04-28T20:28:10.894Z",
  "data": {
    "id": "db746ccf-6dce-4019-b34b-b35a957cb5aa",
    "signature": "db746ccf6dce4019b34bb35a957cb5aa", // settlement reference; only present on advanced stablecoin settlement paths
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    // gasFees is only non-zero on advanced stablecoin settlement paths; otherwise 0
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "subscription": {
      "_id": "680fe4d832ddccc1ee91885e",
      "customer": "66ce47a1e487adc8f4ab0d46",
      "merchant": "66311727a26b3cb28faaf97d",
      "plan": {
        "amount": {
          "cents": 500,
          "currency": "USD"
        },
        "_id": "67bf86d03716ba82ce5cd096",
        "merchant": "66311727a26b3cb28faaf97d",
        "name": "creator1234",
        "code": "music_access",
        "interval": "Monthly",
        "duration": 12,
        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
        "active": true,
        "__v": 0
      },
      "cardProcessor": "mock",
      "reference": "f008bb21-f6a1-4947-b271-90e78638f379",
      "nextPaymentAt": "2025-05-28T20:28:08.164Z",
      "status": "Active",
      "webhookInfo": {
        "item": "sword"
      },
      "createdAt": "2025-04-28T20:28:08.169Z",
      "updatedAt": "2025-04-28T20:28:08.169Z",
      "__v": 0
    },
    "merchantId": "testtest",
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}

// Sent when a subscription renewal card is authorized but not yet captured
{
  "eventType": "Card Payment Authorized",
  "category": "Purchase",
  "created": "2025-04-28T20:31:19.543Z",
  "data": {
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "merchantId": "testtest",
    "id": "39ffc711-8023-46cf-b6ad-5dac81afec88",
    "subscription": {
      "_id": "67d07938a899c293e0ae2147",
      "customer": "67d07935a899c293e0ae2132",
      "merchant": "66311727a26b3cb28faaf97d",
      "plan": {
        "amount": {
          "cents": 500,
          "currency": "USD"
        },
        "_id": "67bf86d03716ba82ce5cd096",
        "merchant": "66311727a26b3cb28faaf97d",
        "name": "creator1234",
        "code": "music_access",
        "interval": "Monthly",
        "duration": 12,
        "description": "Monthly subscription for fans to gain access to listen to Creator 1234 songs",
        "active": true,
        "__v": 0
      },
      "cardProcessor": "mock",
      "reference": "148a2d77-c025-4c48-bccb-f8474ffcf903",
      "nextPaymentAt": "2025-05-11T17:56:08.261Z",
      "status": "Active",
      "webhookInfo": {
        "item": "sword"
      },
      "createdAt": "2025-03-11T17:56:08.262Z",
      "updatedAt": "2025-04-11T20:30:00.146Z",
      "__v": 0
    },
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}

// Sent when a subscription renewal card is declined by the issuing bank
{
  "eventType": "Card Payment Declined",
  "category": "Purchase",
  "created": "2025-04-28T20:21:50.163Z",
  "data": {
    "webhookInfo": {
      "item": "sword"
    },
    "subtotal": {
      "cents": 500,
      "currency": "USD"
    },
    "fees": {
      "cents": 46,
      "currency": "USD"
    },
    "gasFees": {
      "cents": 0,
      "currency": "USD"
    },
    "chargebackProtectionFees": {
      "cents": 0,
      "currency": "USD"
    },
    "total": {
      "cents": 546,
      "currency": "USD"
    },
    "merchantId": "testtest",
    "id": "bce7ca59-4bcc-43c3-95f1-51f2858b0bd2",
    "declineCode": "59",
    "declineDescription": "The transaction is suspected of fraud.",
    "customerId": "cust_abc123",
    "rawCustomerId": "cust_abc123"
  }
}

Schema

Subscription Lifecycle Event Schema

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

{
  "eventType": "string",
  "category": "Subscription",
  "created": "string (ISO 8601)",
  "data": {
    "planCode": "string",
    "planName": "string",
    "subscriptionId": "string",
    "customerId": "string",
    "amount": { "cents": "number", "currency": "string" },
    "interval": "string (Monthly | Yearly | Weekly | Daily)",
    "fundingMethod": "string (Card)",
    "webhookInfo": { "key": "value" },
    "reason": "string (optional — present on Canceled and Expired events)"
  }
}

Subscription Payment Event Schema

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

{
  "eventType": "string",
  "category": "Purchase",
  "created": "string (ISO 8601)",
  "data": {
    "id": "string",
    "signature": "string (present on Settled)",
    "webhookInfo": { "key": "value" },
    "subtotal": { "cents": "number", "currency": "string" },
    "fees": { "cents": "number", "currency": "string" },
    "gasFees": { "cents": "number", "currency": "string" },
    "chargebackProtectionFees": { "cents": "number", "currency": "string" },
    "total": { "cents": "number", "currency": "string" },
    "merchantId": "string",
    "customerId": "string",
    "rawCustomerId": "string",
    "declineCode": "string (present on Card Payment Declined)",
    "declineDescription": "string (present on Card Payment Declined)",
    "subscription": {
      "_id": "string",
      "status": "string (Active | Canceled | Expired)",
      "nextPaymentAt": "string (ISO 8601)",
      "plan": {
        "code": "string",
        "name": "string",
        "interval": "string",
        "duration": "number",
        "amount": { "cents": "number", "currency": "string" }
      },
      "webhookInfo": { "key": "value" }
    }
  }
}