Cleeng Webhooks

Webhooks are notifications that Cleeng sends out to subscribed publishers 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 publisher 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, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
    "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 publisher 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 Support Team to configure for which specific subscription periods this webhook should be sent.

Use case:

Sending notifications

{
    "broadcasterId": 123123123, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
    "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, // same as  publisherId
  "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, // same as  publisherId
  "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, // same as  publisherId
  "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, // same as  publisherId
    "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, // same as  publisherId
    "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 publisher, for example via Update subscription endpoint).

{
  "broadcasterId": 123123123, // same as  publisherId
  "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"
  }
}

Pause-related:

subscriptionPauseScheduled

Trigger:
The event is triggered whenever a subscription pause is scheduled by calling the Pause subscription endpoint.

{
 "broadcasterId": 558186818, // same as  publisherId
 "topic": "subscriptionPauseScheduled",
 "data": {
   "requestedAt": "ATOM",
   "subscriptionId": 123123123,
   "customerId": 222222222,
   "customerEmail": "[email protected]",
   "customerExternalId": "12a1a1ab-1234-1a12-abc1-abc1abc12a12",
   "pauseDate": "ATOM",
   "resumeDate": "ATOM",
   "expirationDate": "ATOM"
 }
}

subscriptionPaused

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

{
 "broadcasterId": 558186818, // same as  publisherId
 "topic": "subscriptionPaused",
 "data": {
   "subscriptionId": 123123123,
   "customerId": 222222222,
   "customerEmail": "[email protected]",
   "customerExternalId": "12a1a1ab-1234-1a12-abc1-abc1abc12a12",
   "pauseDate": "ATOM",
   "resumeDate": "ATOM",
   "expirationDate": "ATOM"
 }
}

subcriptionResumed

Trigger:
The event is triggered in the following cases:

whenever a subscription is resumed after a pause
whenever you resume from an active subscription with scheduled pause (then no pause will be scheduled).

{
 "broadcasterId": 558186818, // same as  publisherId
 "topic": "subscriptionResumed",
 "data": {
   "resumedAt": "ATOM",
   "subscriptionId": 123123123,
   "customerId": 222222222,
   "customerEmail": "[email protected]",
   "customerExternalId": "12a1a1ab-1234-1a12-abc1-abc1abc12a12",
   "resumeType": 'immediate`|`scheduled',
   "pauseDate": "ATOM",
   "resumeDate": "ATOM",
   "expirationDate": "ATOM",
   "paymentId": null | 333444555
 }
}

subscriptionResumeFailed

Trigger:
The event is triggered whenever an attempt to resume a subscription after a pause fails.

{
 "broadcasterId": 558186818, // same as  publisherId
 "topic": "subscriptionResumeFailed",
 "data": {
   "failedAt": "ATOM",
   "subscriptionId": 123123123,
   "customerId": 222222222,
   "customerEmail": "[email protected]",
   "customerExternalId": "12a1a1ab-1234-1a12-abc1-abc1abc12a12",
   "pauseDate": "ATOM",
   "resumeType": 'immediate`|`scheduled',
   "resumeDate": "ATOM",
   "expirationDate": "ATOM",
   "paymentId": null | 333444555
 }
}

subscriptionScheduledResumeReminder

Trigger:
The event is triggered whenever a reminder should be sent to a subscriber about coming subscription resume after a pause.

{
 "broadcasterId": 558186818, // same as  publisherId
 "topic": "subscriptionScheduledResumeReminder",
 "data": {
    "subscriptionId": 123123123,
    "customerId": 222222222,
    "customerEmail": "[email protected]",
    "customerExternalId": "73a2e8ce-6071-4a90-aba0-cea2eda51f29",
    "pauseDate": "ATOM",
    "resumeDate": "ATOM",
    "expirationDate": "ATOM"
  }
}