Webhooks Overview

Webhooks are real-time HTTP POST requests sent to the endpoints you provide. In this way, your servers can be informed by Cleeng about events and be notified of new transactions, payment notifications, and more. These are notifications that Cleeng sends to subscribed broadcasters about specific events on their platforms.

The events are sent in the form of a POST request to specified endpoints with a JSON payload as the body. Whenever this trigger event occurs in the source page, it is immediately recognized by the webhook, collects the data, and sends it to the URL specified as an HTTP request.

The body of the request consists of the following 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.

Prerequisites

Once installed, the webhook will be triggered each time one or more subscribed events occurs.

Here’s a list of the requirements to use Webhooks:

• Must have a Cleeng Broadcaster account. To login, you may go to this link

• When you create an account, you automatically receive a publisher token, which is very necessary to use the API. To find your API key, sign in to Cleeng and go to this link.

• At Cleeng, we make sure that our broadcasters are able to use their test environments to avoid having to test their implementations on live environments when setting up an event, and to familiarize themselves with the dashboard before going live. We are proud to introduce our Cleeng Sandbox. To learn more, please visit our FAQ page.

• An endpoint. You need to have a script available under a publicly accessible URL so that Cleeng can connect to it and send notifications.

• Select your webhooks. The list of available webhooks (general topics) is available here and subscription topics - here.

Scenarios

In order to give you a better overview of how webhooks work, here are a few examples:

transactionCreated

As a broadcaster, you are definitely excited when a new customer arrives and makes a purchase, or an existing customer pays for the next billing period of your subscription. If you want to know about it as soon as it happens, this is the Webhook event for you.

customerRegistered

When a new customer purchases content from you, or registers using your embedded checkout, you get a newCustomer notification to let you know that your user base has grown.

subscriptionReadyForPaymentAuthorisation

If you've already subscribed to that Webhook event, you can track your viewer's payment transactions. For example, if you want to get a notification whenever a payment authorization should occur for a customer, this is the event you want to subscribe to.

subscriptionReadyForPaymentCapture

Whenever a payment capture attempt should be made for a customer, if you're subscribed to this webhook event we will let you know as soon as it happens.

subscriptionReadyForTermination

If a customer failed to pay for their subscription, or they manually canceled it, this notification is being sent when the termination of their subscription is about to happen.

Use Cases

Webhooks provide you with near real-time notifications about status changes. Here you can see a few use cases that show how you might utilize them:

1. Custom notifications

Cleeng by default delivers email notifications for various events. These email notifications are customizable to some extent. If a broadcaster needs more customizations regarding text or graphics, or wants to send notifications via a different channel, then they can subscribe to selected webhook topics and use webhooks as triggers for sending notifications, such as SMS, push notifications, etc. from other tools.

For example, the paymentRejected webhook can be used to inform a customer about problems with payment (e.g., when wrong credit card credentials are provided, such as wrong CVC code, credit card expiry date, etc.)

The subscriptionReactivated webhook can be used to let a customer know that his/her subscription is active again.

2. Caching of entitlements

Notifications about changes of a subscription status can be used to make respective changes in broadcasters’ systems if they have their own entitlement engine.

3. Win-back campaigns

Webhook topics that inform for example about a canceled subscription can be used as a trigger to send a discount coupon code or any other incentive to win a customer back. (The delivery channel depends on the broadcaster, but push notifications might be best here).

4. Payment handling

Webhook events are used to trigger payments in external payment gateways, carrier billing, etc.

Examples

See the table below for examples of webhook topics that can be used for different use cases:

Some quick FAQ's

How many endpoints are required in order to subscribe?
You can use up to 10 endpoints, but at least one is required to subscribe to a webhook topic.

How do I test it?
Make sure you have a Cleeng Sandbox account.

Do I need any authentication to receive webhooks?
No.

Is this free of charge?
Yes, and it is available to all broadcasters.