The MCLS Asynchronous API allows notifications to be sent your systems when changes are triggered in the system. This is very useful when creating more complex applications using MCLS. An example would be to be notified when a stream is being published to then execute workflows such as updating a page or update your internal databases with contents from our API.
You can find an example repository here:
To be able to let the MCLS Asynchronous API call you service we will have to create an Integration. An integration will tell our system which resource to sent an update to and where to send it. Your service will need to handle the incoming request.
To create an integration you will need to specify:
A Target (Webhook)
A source (Events, streams etc)
Currently the only supported target is a webhook.
The full integrations API documentation can be found here:
To create an integration you will need to use the following API endpoint:
The payload looks like this:
"authorization": "Basic YWxhZGRpbjpvcGVuc2VzYW1l"
For the source you have the following options available:
SOURCE_EVENTS: Sends an update whenever event gets updated
SOURCE_STREAM: Sends an update whenever stream gets updated
SOURCE_STREAM_URL: Sends an update whenever stream URL gets updated
You can find the most up-to-date sources here.
The URL field needs to contain the full URL of your webhook (including HTTP(s)://).
The "Headers" field can be used to send specific headers along with the request we make to your webhook. This can be useful when you want to send an authorization token for example to authenticate the request.
The "Params" field is used to send key/value arguments of your choice with the request. These will be sent as query parameters when we call your webhook.
After creation you will get the receive the following payload:
"authorization": "Bearer YWxhZGRpbjpvcGVuc2VzYW1l"
This payload contains the ID of the integration, you will need to store this in your system so you can delete or update the integration later.
After the integration has been created, simply test it by doing an operation on a stream, such as creating a new stream, editing a stream, publish a stream, start transcoding etc. Every time the state of a stream changes the webhook will now be called.
The payload that's sent by the webhook looks like this
If you specified any params in the "Params" field they will not be sent in the payload, but as query parameters. Headers you provided will also be sent when the Asynchronous API sends the request.