API Tutorials
HELP CENTERINTEGRATIONSSTATUS PAGESIGN UP

Webhook - General Topics

Suggest Edits

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 General Topics

transactionCreated

Trigger:
The event is triggered whenever a new transaction is made on the broadcaster’s content or subscriptions. The subscriptionPlanId field value is an ID of a subscription plan the transaction has been made for, or null if a transaction has been made on content purchase.

The event is triggered both for initial payments and recurring billing.

Use case:

  • Sending notifications
{
    "broadcasterId": 558186818,
    "topic": "transactionCreated",
    "data": {
        "offerId": "S123321123_BY",
        "transactionId": "T111333222",
        "customerId": 332442553,
        "paymentId": 1536331075,
        "offerPrice": 5.25,
        "offerCurrency": "USD",
        "discountRate": null,
        "subscriptionPlanId": 543221430,
        "externalData": "data",
        "customerEmail": "[email protected]",
        "customerExternalId": "123456789",
        "paymentGateway": "adyen"
    }
}

customerRegistered

Trigger:
The event is triggered whenever a new customer is registered using broadcaster’s checkout or registerCustomer API, or an existing Cleeng customer purchases broadcaster’s content or subscription for the first time.

Use case:

  • Sending notifications
  • Third-party integration (e.g. identity, marketing)
{
    "broadcasterId": 558186818,
    "topic": "customerRegistered",
    "data": {
        "customerId": 593300903,
        "customerEmail": "[email protected]",
        "customerExternalId": "123456789"
    }
}

customerRequestedPasswordReset

Trigger:

The event is triggered whenever a customer wants to reset their password (e.g. password reset can be triggered by Reset password API).

Please note that the passwordResetUrl is configurable via the resetUrl parameter of Reset password endpoint. You can see examples with default and custom passwordResetUrl below.

Use case:

  • Sending notifications

Example with default passwordResetUrl:

{  
    "customerId": 123456789,  
    "customerEmail": "[email protected]",  
    "passwordResetUrl": "https://cleeng.com/generate-password/?email=email%40domain.com&resetPasswordToken=836e2dd52a62cb726d55f4c35dbc6ff661d8c521&publisherId=114098951"
}

Example with custom passwordResetUrl:

{  
    "customerId": 123456789,  
    "customerEmail": "[email protected]",  
    "passwordResetUrl": “https://example.your-domain.com?email=email%40domain.com&resetPasswordToken=836e2dd52a62cb726d55f4c35dbc6ff661d8c521&publisherId=114098951"
}

customerConsentUpdated

Trigger:
The event is triggered whenever a customer changes a consent settings.

Use case:

  • Sending notifications
  • Third-party integration (e.g. identity, marketing)
{
    "broadcasterId": 558186818,
    "topic": "customerConsentUpdated",
    "data": {
        "customerId": 593300903,
        "customerEmail": '[email protected]',
        "consentName": "broadcaster_marketing",
        "consentState": "accepted",
        "consentChangeDate": "2019-05-16T09:45:13+02:00"
    }
}

capturePayment

Trigger:
The event is triggered when payment capture is required by the Cleeng platform. This happens during subscription switch situations that involve payment, for example for the following switch algorithms:

Use cases:

  • Payment handling
{
  "broadcasterId": 111111111,
  "topic": "capturePayment",
  "data": {
	"subscriptionId": 321321321,
	"orderId": 123456789,
	"paymentDetailsId": 811837427,
	"paymentMethodId": 123123123
  }
}

refundPayment

Trigger:
The event is triggered whenever a refund is requested. It is sent from the Cleeng platform to a connector. A connector should react to it and transfer funds back to the customer.

{
    "broadcasterId": 558186818,
    "topic": "refundPayment",
    "data": {
        "paymentId": 123123123,
        "paymentGateway": "adyen",
        "externalPaymentId": "ask3ekv-vmdmskxyz",
        "customerId": 123123123,
        "customerEmail": "[email protected]",
        "orderId": 123123123,
        "paymentMethodId": 123123123,
        "amount": 10.33,
        "reason": "Payment refund requested"
    }
}

paymentRefundAccepted

🚧

Available only for Bambora Payment Gateway.

Trigger:
The event is triggered from the broadcaster dashboard 'Cancel this transaction' button.

Use cases:

  • Sending notifications
  • Caching of entitlements
  • Win-back campaigns
  • Payment handling
{
    "broadcasterId": 558186818,
    "topic": "paymentRefundAccepted",
    "data": {
        "paymentId": 123123123,
        "paymentGateway": "bambora",
        "customerId": 123123123,
        "customerEmail": "[email protected]",
        "orderId": 123123123,
        "externalPaymentId": "ask3ekv-vmdmskxyz",
        "paymentMethodId": 123123123
    }
}

paymentRefunded

Trigger:

The event is triggered when a payment has been refunded. It is emitted when a payment refund process is completed - when a connector notifies about the fact that funds have been returned to the customer.

Use case:

  • Sending notifications
{
    "broadcasterId": 558186818,
    "topic": "refundPayment",
    "data": {  
         "paymentId": 1234567890,  
         "paymentGateway": "paypal",  
         "externalPaymentId": "5NP123456B654321Y",  
         "customerId": 987654321,  
         "amount": 22,  
         "offerId": "S123123123_US"  
   }      
}

paymentDetailsDeactivated

Trigger:
The event is triggered when payment details stop being used for recurring payments, for example when active payment details are deleted or new active payment details are created.

It is useful for cancelling authorized payments if they exist at the time of payment details change.

Use cases:

  • Sending notifications
  • Payment handling
{
    "broadcasterId": 402171721,
    "topic": "paymentDetailsDeactivated",
    "data": {
        "paymentDetailsId": 811837427,
        "paymentMethodId": 611593213,
        "customerId": 965936709
    }
}

paymentRejected

Trigger:
The event is triggered when a payment attempt fails, for example when wrong credit card credentials are provided (e.g. wrong CVC code, credit card expiry date, etc.), or when there are not sufficient funds for a recurring payment to take place.

It is triggered both for initial and recurring payments.

Use cases:

  • Caching of entitlements
  • Payment handling
  • Sending notifications

It is useful for sending emails to customers informing them about payment issues. Please note that the mechanism is applicable when emails are managed externally (outside of Cleeng).

{
    "broadcasterId": 123456789,
    "topic": "paymentRejected",
    "data": {
        "offerId": "S123321123_BY",
        "paymentPrice": 5.25,
        "paymentCurrency": "USD",
        "paymentMethod" : "visa",
        "paymentGateway" : "adyen",
        "customerId": 987654321,
        "customerEmail": "[email protected]",
        "recurringPayment" : true
        "successiveRejectionNumber" : 1, 
        "failureReason" : "CVC Declined"
    }
}

Note:
successiveRejectionNumber returns the number of failed attempts. The counter is reset in two cases:

  1. when payment method is replaced
  2. when payment for given payment detail is successful.

cardExpiresSoon

Trigger:
The event is triggered when a subscriber’s credit card used for recurring billing expires before the next payment date. It is triggered:

  • 21 days before card expiration date
  • 5 days before card expiration date

Note: cardExpiresSoon event is triggered only for payment details that are connected with an active subscription.

Use case:

  • Sending notifications
{
  "broadcasterId": 123123123,
  "topic": "cardExpiresSoon",
  "data": {
    "customerId": 987654321,
    "paymentDetailsId": 255888155,
    "paymentMethodId": 321321321,
    "cardHolderName": "John Doe",
    "cardExpirationDate": "2022-08-31",
    "customerExternalId": "9a39eecb-0554-4a8e-b189-3056fdafbbb6"
  }
}

giftReadyForDelivery

Trigger:
The event is triggered whenever a gift delivery time is reached and a notification should be sent informing about a gift.

{
    "broadcasterId": 123123123,
    "topic": "giftReadyForDelivery",
    "data": {
        "code": "ABCD-0000",
        "offerId": "S123123123_US",
        "gifterEmail": "[email protected]",
        "gifterId": 123456789,
        "recipientEmail": "[email protected]",
        "personalNote": "Happy Birthday"
    }
}

Updated 4 days ago