Webhook - Subscription Topics

Cleeng Webhooks

Webhooks are notifications that Cleeng sends out to subscribed broadcasters about certain events occurring in the platform. The events are sent in the form of a POST request made to specified endpoints with a JSON payload as its body.

The body of the request consists of three constant fields:

broadcasterId – the ID of the broadcaster that the webhooks is sent for,
topic – the name of the topic that the webhook is sent about,
data – topic-specific payload about the event.

Available Subscription Topics

subscriptionReadyForPaymentAuthorisation

Trigger:
The event is triggered whenever a payment authorization attempt should be made for a given subscription.

Use case:

Payment handling (external payment gateways, carrier billing,etc.)

🚧
subscriptionReadyForPaymentAuthorisation is required for recurring payments.

{
    "broadcasterId": 558186818,
    "topic": "subscriptionReadyForPaymentAuthorisation",
    "data": {
        "subscriptionId": "332332332",
        "offerId": "S123123123_US",
        "customerId": 123321123,
        "customerEmail": '[email protected]'
        "paymentDetailsId": 665665665,
        "active": true,
        "dunningAttemptDate": "2019-11-04T19:55:41Z",
        "dunningStatus": "authorize",
        "expirationDate": "2019-11-07T19:55:41Z",
        "currency": "USD",
        "paymentCountry": "BY",
        "paymentMethodId": 123123123,
        "token": "tok_en",
        "paymentGateway": "adyen"
    }
}

subscriptionReadyForPaymentCapture

Trigger:
The event is triggered whenever a payment capture attempt should be made for a given subscription.

Use case:

Payment handling (external payment gateways, carrier billing,etc.)

🚧
subscriptionReadyForPaymentCapture is required for recurring payments.
iDEAL exception: You don’t need to subscribe to subscriptionReadyForPaymentCapture webhook for this payment method. iDEAL captures payments automatically.

{
    "broadcasterId": 558186818,
    "topic": "subscriptionReadyForPaymentCapture",
    "data": {
        "subscriptionId": 121780131,
        "offerId": 'S729964196_CA',
        "customerId": 388082979,
        "customerEmail": '[email protected]',
        "paymentDetailsId": 255888155,
        "active": true,
        "dunningAttemptDate": '2019-03-03T09:43:20+01:00',
        "dunningStatus": 'capture',
        "expirationDate": '2019-03-06T09:43:20+01:00',
        "currency": 'USD',
        "token": 'tok_en',
        "paymentId": 123456789,
        "externalPaymentId": 'externalId',
        "orderId": 123123123,
        "paymentGateway": "adyen"
    }
}

Please note that the following payload parameters can be null:

paymentId
orderId
externalPaymentId

Such a situation happens if there hasn't been payment authorization before payment capture. This is the case if the recurring billing process consists of just one stage: capture.

subscriptionStopped

Trigger:
The event is triggered whenever a subscription is stopped.

Use cases:

Sending notifications
Caching of entitlements
Win-back campaigns

{
    "broadcasterId": 123123123,
    "topic": "subscriptionStopped",
    "data": {
        "subscriptionId": 123123123,
        "subscriptionExternalId": "I-GHF2VR4V5U33",
        "offerId": "S123456789_PL",
        "customerId": 593300903,
        "customerEmail": "[email protected]",
        "customerExternalId": "123456789",
        "paymentGateway": "adyen"
    }
}

subscriptionRenewalPrenotification

Trigger:
The event is triggered 30 days before the subscription expiration date. It informs about the upcoming subscription renewal so that a broadcaster can send an email to a customer.
The supported subscription offer periods are:

3 months,
6 months,
annual,
seasonal.

Note:
If you are subscribed to this webhook, then by default we send this webhook for annual subscriptions only. Please contact Cleeng Broadcaster Success Specialists to configure for which specific subscription periods this webhook should be sent.

Use case:

Sending notifications

{
    "broadcasterId": 123123123,
    "topic": "subscriptionRenewalPrenotification",
    "data": {
        "subscriptionId": 123123123,
        "offerId": "S123123123_PL",
        "customerId": 987654321,
        "customerEmail": "[email protected]",
        "active": true,
        "expirationDate": "2039-03-06T09:43:20+01:00",
        "customerExternalId": "123456789",
        "customerFirstName": "Joe",
        "customerLastName": "Doe",
        "nextPaymentPrice": 5.25,
        "nextPaymentCurrency": "AUD",
        "nextPaymentAt": 1668595355,
        "paymentGateway": "adyen",
        "offerBillingCycle": [
            "amount": 1,
            "periodUnit": "year"
        ]
    }
}

subscriptionRenewed

Trigger:
The event is triggered after recurring or when a subscription switch with charge takes place.

Use cases:

Sending notifications
Caching of entitlements

Note:
If the subscriptionRenewed webhook is triggered when the subscription switch takes place, then the offerSwitchId is provided. Otherwise it is null.

Please note that for subscription switches (upgrades, downgrades), both subscriptionRenewed and subscriptionSwitched (see here) webhooks can be triggered. They can be triggered together or separately, depending on whether the switch and a successful transaction for a new period happen at the same time or not (this depends on the algorithm used for subscription switches).

{
    "broadcasterId": 123123123,
    "topic": "subscriptionRenewed",
    "data": {
        "subscriptionId": 123123123,
        "offerId": "S123123123_PL",
        "offerSwitchId”: “240fd50f-f0ac-430e-b3d0-97b2b57690ea",
        "customerId": 987654321,
        "customerEmail": "[email protected]",
        "active": true,
        "expirationDate": "2019-03-06T09:43:20+01:00",
        "customerExternalId": "123456789",
        "paymentGateway": "adyen"
    }
}

subscriptionReactivated

Trigger:
The event is triggered whenever a subscription is reactivated (change subscription status from canceled (stopped) into active)

Use cases:

Sending notifications
Caching of entitlements

{
    "broadcasterId": 123123123,
    "topic": "subscriptionReactivated",
    "data": {
        "subscriptionId": 123123123,
        "offerId": "S123123123_PL",
        "customerId": 987654321,
        "customerEmail": "[email protected]",
        "active": true,
        "expirationDate": "2019-03-06T09:43:20+01:00",
        "customerExternalId": "123456789",
        "paymentGateway": "adyen"
    }
}

subscriptionReadyForTermination

Trigger:
The event is triggered whenever a subscription should be terminated.

Use cases:

Sending notifications
Caching of entiltements
Win-back campaigns
Payment handling

🚧
subscriptionReadyForTermination is required for recurring payments.

{
    "broadcasterId": 558186818,
    "topic": "subscriptionReadyForTermination",
    "data": {
        "offerType": "subscription",
        "subscriptionId": "332332332",
        "offerId": "S123123123_US",
        "customerId": 123321123,
        "customerEmail": "[email protected]",
        "paymentDetailsId": 665665665,
        "active": true,
        "dunningAttemptDate": "2019-11-04T19:55:41Z",
        "dunningStatus": "capture",
        "expirationDate": "2019-11-07T19:55:41Z",
        "subscriptionExternalId": "I-GHF2VR4V5U98",
        "token": "token_en",
        "customerExternalId": "123456789",
        "paymentGateway": "adyen"
    }
}

subscriptionCreated

Trigger:
The event is triggered whenever a subscription is created.

Use cases:

Sending notifications
Caching of entitlements

{
    "broadcasterId": 558186818,
    "topic": "subscriptionCreated",
    "data": {
        "offerType": "subscription",
        "subscriptionId": "332332332",
        "offerId": "S123123123_US",
        "customerId": 123321123,
        "customerEmail": "[email protected]",
        "active": true,
        "dunningAttemptDate": "2019-11-04T19:55:41Z",
        "dunningStatus": "capture",
        "expirationDate": "2019-11-07T19:55:41Z",
        "customerExternalId": "123456789",
        "inTrial": false,
        "pendingSwitchId": fd55c5be-919a-4b7b-9a7a-3bc09bca9f00,
        "paymentGateway": "adyen"
    }
}

subscriptionTerminated

Trigger:
The event is triggered whenever a subscription is terminated.

Use cases:

Sending notifications
Caching of entitlements
Win-back campaigns

{
    "broadcasterId": 558186818,
    "topic": "subscriptionTerminated",
    "data": {
        "offerType": "subscription",
        "subscriptionId": "332332332",
        "offerId": "S123123123_US",
        "customerId": 123321123,
        "customerEmail": "[email protected]",
        "customerExternalId": "123456789",
        "inTrial": false,
        "paymentGateway": "adyen"
    }
}

subscriptionTrialConverted

Trigger:
The event is triggered when a subscription moves out of trial (the trial period ends and the subscription status changes to paid subscription).

Use cases:

Sending notifications
Caching of entitlements

{
  "broadcasterId": 558186818,
  "topic": "subscriptionTrialConverted",
  "data": {
    "offerType": "subscription",
    "subscriptionId": "332332332",
    "offerId": "S123123123_US",
    "customerId": 123321123,
    "customerExternalId": "ext-123321123",
    "customerEmail": "[email protected]",
    "active": true,
    "expirationDate": "2019-11-07T19:55:41Z",
    "paymentId": 111222333,
    "offerSwitchId": "e1ee6933-7c30-4cfa-bc27-7097f7d1552b",
    "paymentGateway": "adyen"
  }
}

offerSwitchId is present only if a trial has been finalized as a result of subscription switch (upgrade or downgrade), otherwise it is null.

subscriptionSwitched

Trigger:
The event is triggered after a subscription upgrade or downgrade takes place.

The webhook is also available for iOS & tvOS, Android and Roku.

{
  "broadcasterId": 558186818,
  "topic": "subscriptionSwitched",
  "data": {
    "id": "240fd50f-f0ac-430e-b3d0-97b2b57690ea",
    "customerId": 111222333,
    "fromOfferId": "S653123187_PL",
    "toOfferId": "S278490202_PL",
    "subscriptionId": 123456789
    “algorithm”: “DEFERRED”,
    “direction": "downgrade",
    “status”: “finished”,
    “customerEmail”: “[email protected]”,
    “customerExternalId”: null,
    “createdAt”: 1661777515,
    “updatedAt”: 1661777705
  }
}

Note:
Please note that for subscription switches (upgrades, downgrades), both subscriptionSwitched and subscriptionRenewed (see here) webhooks can be triggered. They can be triggered together or separately, depending on whether the switch (e.g. upgrade) and a successful transaction for a new period happen at the same time or not (this depends on the algorithm used for subscription switches).

If, for example, an IMMEDIATE AND CHARGE… or DEFERRED algorithm is used, both a subscription switch and a transaction for a new period happen at the same time, so both webhooks are triggered.

If, on the other hand, an IMMEDIATE_WITH_TIME_PRORATION algorithm is used - a subscription switch happens immediately but the transaction is delayed by the time resulting from proration. In such a situation the webhooks will be triggered separately - first, subscriptionSwitched when the customer gets access to the new plan, and then subscriptionRenewed - when the successful transaction takes place.

subscriptionSwitchRequested

Trigger:
The event is triggered whenever an upgrade or downgrade attempt is made for a given subscription (whenever a customer requests upgrade or downgrade of their subscription).

{
  "broadcasterId": 558186818,
  "topic": "subscriptionSwitchRequested",
  "data": {
    "id": "240fd50f-f0ac-430e-b3d0-97b2b57690ea",
    "customerId": 111222333,
    "fromOfferId": "S653123187_PL",
    "toOfferId": "S278490202_PL",
    "subscriptionId": "123456789",
    "algorithm": "DEFERRED",
    "direction": “downgrade”,
    "status": “pending”,
    "customerEmail": "[email protected]",
    "customerExternalId": null,
    "createdAt": 1661337280,
    "updatedAt": 1661337280
  }
}

subscriptionSwitchFailed

Trigger:
The event is triggered whenever a subscription upgrade or downgrade fails.

Use case:

sending notifications

{
    "broadcasterId": 558186818,
    "topic": "subscriptionSwitchFailed",
    "data": {
        "id": "240fd50f-f0ac-430e-b3d0-97b2b57690ea",
        "customerId": 111222333,
        "fromOfferId": "S653123187_PL",
        "toOfferId": "S278490202_PL",
        "subscriptionId": "123456789",
        "algorithm": "DEFERRED",
        "direction": "downgrade",
        "status": "failed",
        "customerEmail": "[email protected]",
        "customerExternalId": null,
        "createdAt": 1661777938,
        "updatedAt": 1661778034
    }
}

subscriptionSwitchCancelled

Trigger:
The event is triggered whenever a switch is canceled by a customer or system (if another switch for the same subscription has been requested).

{
    "broadcasterId": 558186818,
    "topic": "subscriptionSwitchCancelled",
    "data": {
        “id”: “240fd50f-f0ac-430e-b3d0-97b2b57690ea”,
        "customerId": 111222333,
        "fromOfferId": "S653123187_PL",
        "toOfferId": "S278490202_PL",
        "subscriptionId": "123456789",
        "direction": "downgrade",
        "status": “cancelled”,
        "algorithm": “DEFERRED”,
        "customerEmail": “[email protected]”,
        "customerExternalId": null,
        "createdAt": 1661778522,
        "updatedAt": 1661778543
    }
}

subscriptionExtended

Trigger:

The event is triggered whenever a subscription or pass is extended (its expiration date is extended by a broadcaster, for example via Update subscription endpoint).

{
  "broadcasterId": 123123123,
  "topic": "subscriptionExtended",
  "data": {
    "subscriptionId": 123456789,
    "offerId": "S987654321_US",
    "customerId": 321321321,
    "customerExternalId": null,
    "customerEmail": "[email protected]",
    "expirationDate": "2024-06-08T11:05:50+02:00",
    "paymentGateway": "adyen"
  }
}