Webhook - General 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 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.

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"
    }
}

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"
    }
}

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"
    }
}

refundPayment

Trigger:
The event is triggered whenever a refund for an external payment method is requested.

🚧

The refundPayment webhook is not emitted if a refund is requested for Moneris.

{
    "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 and AltaPay Payment Gateways.

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
    }
}

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"
  }
}