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 thesubscriptionRenewed
webhook is triggered when the subscription switch takes place, then theofferSwitchId
is provided. Otherwise it isnull
.Please note that for subscription switches (upgrades, downgrades), both
subscriptionRenewed
andsubscriptionSwitched
(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), bothsubscriptionSwitched
andsubscriptionRenewed
(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 thensubscriptionRenewed
- 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"
}
}
Updated 3 months ago