Our new notification service gives you real time status updates on your video encodings with RESThooks.
Have you ever been on a family holiday and had your kids nagging you the entire way: “Are we there yet, are we there yet!?”. If you have, then you have some idea what it is like for an application trying to find out if a process has finished running. Constant requests for the current state of a process can be resource intensive, not to mention annoying.
Polling the state of an encoding job in your adaptive video workflow is a perfect example of this situation. It requires extra implementation and maintenance and also increases the server load. It would be much more efficient for our system to notify your system as soon as the encoding is complete. We aren’t holding out too much hope that the kids will settle for this workflow, but we can now offer exactly this solution for your encoding infrastructure through the latest version of our API.
How does it work?
Due to the many and varied methods available for implementing webhooks there were a lot of different potential solutions. A REST interface was a logical choice and when we came across RESTHooks, we liked it!
In this first release we offer two resources: Events and Subscriptions.
The four events available are:
- encoding.finished
- encoding.error
- transfer.finished
- transfer.error.
We will continue to expand this list in subsequent API releases.
In order for your system to be notified when one of these events fires, you can create a subscription by assigning a callback URL. This URL will receive a POST request with a defined request-body. In the case that our request to your callback-URL fails, we will try it three more times using an exponential backoff strategy, until we mark the triggered event as “aborted”.
And it’s as simple as that. Once that notification hits your system, you can do whatever you like with it to enhance your view and control your encoding processes.
Example Time!
Firstly, you probably want to know which events are available. I already told you that! But it’s a fair question, because by the time I finish typing this post we may have added a few more ;-). Keep up to date with the latest features in our release notes.
GET Notifications/Events
Each event comes with an unique ID which is needed to create a subscription.
Response:
[
{
"id": "46faf62b-4f80-4f8a-b9e4-b23bf050f43c",
"name": "encoding.finished",
"description": "Occurs once an encoding is finished and ready to be transferred or to be consumed by other bitmovin services"
},
{
"id": "c8115a85-4ce9-4836-9023-a6db1b45bd04",
"name": "transfer.finished",
"description": "Occurs once a transfer has finished successfully"
},
{
"id": "175dd18f-602e-449d-8ad8-714645ae2e4e",
"name": "encoding.error",
"description": "Occurs if an encoding has failed"
},
{
"id": "ffcdd105-8fc7-408b-ab1f-ee2090966df2",
"name": "transfer.error",
"description": "Occurs if a transfer has failed"
}
]
POST Notifications/Subscriptions
Creating a subscription for an event is quite easy. All you need is a valid endpoint URL which is able to receive a POST request. The request body for a subscription to the “encoding.finished”-event would look like this:
Request
{
"eventId": "46faf62b-4f80-4f8a-b9e4-b23bf050f43c",
"url": "<your-callback-url>"
}
Response:
{
"id": "<your-subscription-id>",
"event": {
"id": "46faf62b-4f80-4f8a-b9e4-b23bf050f43c",
"name": "encoding.finished",
"description": "Occurs once an encoding is finished and ready to be transferred or to be consumed by other bitmovin services"
},
"url": "<your-callback-url>"
}
GET Notifications/Subscriptions/[id]/Trigger
The subscription-ID from before, can be used to get a list of all events which have been triggered so far. You will get the latest callbackAttempt as well as how often we have tried to send a request to your callback URL.
Response:
[
{
"id": "<event-trigger-id>",
"callbackAttempts": [
{
"id": "<callback-attempt-id-1>",
"connectionTime": "2016-07-15T17:24:36.236",
"attemptNumber": 1,
"errorMessage": null,
"status": "successful",
"responseCode": 200,
"responseData": "ok",
"method": "POST"
}
],
"subscription": {
"id": "<subscription-id>",
"event": {
"id": "<event-id>",
"name": "encoding.finished",
"description": "Occurs once an encoding is finished and ready to be transferred or to be consumed by other bitmovin services"
},
"url": "<your-callback-url>"
},
"payload": "{\"jobId\":123456,\"status\":\"Finished\",\"speed\":\"premium\", ... }",
"status": "completed",
"latestCallbackAttempt": {
"id": "<callback-attempt-id-1>",
"connectionTime": "2016-07-15T17:24:36.236",
"attemptNumber": 1,
"errorMessage": null,
"status": "successful",
"responseCode": 200,
"responseData": "ok",
"method": "POST"
}
}
]
More Examples and Documentation
We have already updated our API reference, where you will find all available calls to interact with that service. We have also integrated our notification-service into the Java API Client. Other API Clients will follow shortly.
As this service is currently a beta, we greatly appreciate your feedback, so please tell us what you think about it, what you like, what you hate, what you think we should add next.
