Using Ziggeo webhooks aka server side events

If you are here you are likely looking into using webhooks - or server side events. Now we know, it all sounds great on paper:

invisible to people visiting your pages
you do not need to check for data yourself every X seconds / minutes
our system does most of the work
you get only what is interesting to you

How do You use it you say? Easy! My snorkel is on, so lets dive in. :)

Now seeing that PHP is likely the most common language used on server side, this is the one that will be used to describe webhooks, however it can be applied to any server side language such as (and certainly not limited to) - Ruby, NodeJS, ASP (Active Server Pages), Python, etc.

First of there are multiple ways of doing it, we will use one, however mention two:

$_POST - if you ever worked with any form and PHP, you have more than likely used $_POST global, so this is probably the most common approach
php://input - not as common, however great for what we need.

The $_POST variable is great when you are using "Use traditional form fields" template (under Application > Manage > Webhooks) however for "Encode as JSON in form" and "JSON encoding" templates you are far better of with php://input approach as $_POST can not detect values properly enough. php://input will of course work with all, so this is the one that we will use in the code demos that follow.

Now you know what we will use and why, so lets first of see how to exactly set up webhooks.

To do that you would:

log into your Ziggeo account dashboard
open the application that you would like to have webhooks sent from
click on Manage submenu that got shown to you
Under this new screen you will see Webhooks.

Now on the webhooks screen the "New Webhook" field would be given the link to your webhook, "Template" dropdown allows you to select the format in which the data is sent over to your server and the "Events" option allows you to select if you want to have your system notified of all events that will fire (you can see the list here) or if you are interested in a single one - and which one(s) at the same time.

When webhooks get fired, they only include video data, so there is not a lot of difference bandwidth wise for your server, however if you like to keep everything clean and simple - minimalistic, you would probably like to have only specific ones sent your way.

As mentioned the difference in bandwidth is so small that it should not matter much, however your system would need to process everything each time it is sent something at which stage it does make some difference.

Having that said, this is still much better than having your system run under cron / crontab or any other sort of mechanism as webhooks minimize your server operations to minimum, the above is just if you like to go even further ;)

Now going back to the webhooks, the template that we use would mostly make a difference in just one part of code - where we initialize our data variable:

$webhook_data = $_POST;

$webhook_data = json_decode( file_get_contents('php://input'), true );

Yup, all the rest of the code is just the same - as said - easy :)

Now, lets consider the most common types of webhooks used. If we do, the top 5 webhooks would be:

webhook fired when video has been created
webhook fired when video has been processed and available for playback
webhook fired when video has been pushed to some service
webhook fired when video had been transcribed and text is available
webhook fired when video analysis data has been done and available

To make sure that we explain each, we will go over complete code for each segment

Video has been created

<?php

    //we check the webhooks responses..
    //remember the above, if we use "Use traditional form field"
    // template, we can use $_POST, however for all of them, we can use php://input 
    $webhook_data = json_decode( file_get_contents('php://input'), true );

    $event_type = $webhook_data['event_type']; //for video created it would be 'video_create'

    $video_data = $webhook_data['data']['video'];

    //lets get token and key
    $video_token = $video_data['token'];
    //we could have written this as $_POST['data']['video']['token'];
    $video_key = $video_data['key'];
    //like the above, we could have written this as $_POST['data']['video']['key'];

    //used tags
    $video_tags = $video_data['tags'];

    $has_video_profile = ( $video_data['video_profile'] !== null ) ? true : false;
    $has_meta_profile = ( $video_data['meta_profile'] !== null ) ? true : false;
    $has_effect_profile = ( $video_data['effect_profile'] !== null ) ? true : false;

    $created_on = date('Y-m-d H:i:s', $video_data['created']); //it is UNIX epoch time hence this formatting

    $custom_data = $video_data['data']; //custom data sent with video

    $device_info = $video_data['device_info']; //if you like to see what system someone was using when creating videos
                                               // (it will not be present on all videos).

    $is_HD = $video_data['hd'];

    //now we have various details, it is up to you if they would be saved in some file,
    // DB or if some action should run when this happens.
?>

Nice, so you got to here, and that means that you already have the code that you need to know when video has been created. All you would do now is to:

save the file
upload it somewhere on your server
grab the link to it
add it to your Webhooks list in the Ziggeo dashboard and you are all set
just upload the video and check your database for info.

You can also grab the demo from our PHP SDK demos here:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/_webhook_for_video_create.php

Video is ready for playback

The great thing about these webhooks is that they are quite repetitive, so all we need is to build upon it further and further, without a need to recreate it.

What that means is that the same code as for video created can be used, or we can go further. For example at video_ready event, we also have streams available, which we can grab through:

$streams = $video_data['streams'];

The complete code would look like so:

<?php

    //we check the webhooks responses..

    $webhook_data = json_decode( file_get_contents('php://input'), true );

    $event_type = $webhook_data['event_type']; //it would be 'video_ready'

    $video_data = $webhook_data['data']['video'];

    //lets get token and key
    $video_token = $video_data['token'];
    //we could have written this as $_POST['data']['video']['token'];
    $video_key = $video_data['key'];
    //like the above, we could have written this as $_POST['data']['video']['key'];

    //used tags
    $video_tags = $video_data['tags'];

    $has_video_profile = ( $video_data['video_profile'] !== null ) ? true : false;
    $has_meta_profile = ( $video_data['meta_profile'] !== null ) ? true : false;
    $has_effect_profile = ( $video_data['effect_profile'] !== null ) ? true : false;

    $created_on = date('Y-m-d H:i:s', $video_data['created']); //it is UNIX epoch time hence this formatting

    $custom_data = $video_data['data']; //custom data sent with video

    $device_info = $video_data['device_info']; //if you like to see what system someone was using when
                                               // creating videos (it will not be present on all videos).

    $is_HD = $video_data['hd'];

    $streams = $video_data['streams']; //at this stage video streams exist,
                                       // and they are objects like video object
    //streams contain additional details specific to video stream.

    //now we have various details, it is up to you if they would be saved in some file,
    // DB or if some action should run when this happens.
?>

If you prefer GitHub view of the demo, check it out here:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/_webhook_for_video_ready.php

Streams are useful when you want to know tokens of individual streams such as of the default stream (standardized 640x480 mp4 file - that is of course per standard settings).

Knowing when the video is ready of course is great way to know when transcoding of your video has been finalized.

Video Stream is pushed

Often, it is interesting to raise popularity over YouTube or Vimeo with a great video, however in the same time to also make sure that your videos are branded with your logo. To do that you would just push that one stream containing video bug and Voila - all done.

As it can be done manually it can also be done automatically through the simple setup of auto-push feature. I know that you are likely already familiar with the same, however if not, you can check out a short info about this great feature here: https://ziggeo.com/features/push-service.

At this time we can use some of the original "base" code, and some extra such as the info about the stream pushed and the service that was used for pushing.

//if we need details about the stream that has been pushed:
$pushed_stream = $webhook_data['data']['stream'];

//if we need details about the service where the video was pushed to..
$push_service_info = $webhook_data['data']['push'];

$push_service_token = $push_service_info['token'];
$push_to = $push_service_info['title']; //this uses title that you had set up for the push service

//if the push was made manually or automatically, this would tell
$is_autopush = $push_service_info['auto_push'];

//what is the type of push service - Google Drive would be  "ApiGoogleDrivePush" for example
$push_service = $push_service_info['type'];

Now if you want to see the complete code, head over to the demo in the PHP SDK where you will see the same info:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/_webhook_for_video_stream_push_success.php

I bet you are thinking about all those cool things you can do with this new knowledge seeing how easy it is to make use of the webhooks and once getting to some place to go even further ... well we know, lets just go over few more samples first ;)

Video's audio transcription / text from video

Grabbing the text of what was said in the video is quite simple. It also gives you a ton of info, not just the text that was there. With it, you can grab the complete text, words per millisecond of the video, keywords, and going even further, system can give you a very confident video topic as well.

This way you can use keywords and topic to automate the detection where the video should be placed (category) and what kind of tags it should be set with, while the complete text is such a great value for your SEO, once you start you will love it present all of the time :)

You can of course see more about it in our features page dedicated for Audio Transcription service.

So here we go with the additional code that would allow us to get right data:

//if we are after text that has been transcribed from the video it is best to grab it from original stream
$transcription_data = $video_data['original_stream']['audio_transcription'];

//comma separated list of all words that were found in video
$words = $transcription_data['words'];
//scores of the words above, allowing you to see how certain our system is
// of that word being there
$word_scores = $transcription_data['scores'];
//comma separated objects with start and end time of the words (same order as words)
$times = $transcription_data['times'];
//complete text of the text received from the video
$entire_text = $transcription_data['text'];
//topic or topics that transcription system thinks is the topic of the video
$video_topic = $transcription_data['topics'];
//not to be confused with audio_keywords, these keywords are based on detected text,
// and such are likely to be slightly more accurate.
$transcribed_keywords = $transcription_data['keywords'];

//keywords that were detected during parsing
$audio_keywords = $video_data['original_stream']['$audio_keywords'];

//with just these details we would be able to setup up a system that
// would collect the words in a given timeframe and quickly create subtitles,
// however of course that is up to you - what you would do with the same :)

Of course as before, you can see the complete demo code in our demos folder in the PHP SDK on GitHub here:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/_webhook_for_video_transcription.php

Video Analysis

Have you watched those spy movies where they grab a video and can tell where something was on the video almost instantly? Well, technology has advanced enough to actually allow you to do something like that in quite a fast timeframe - using video analysis.

If you are community administrator that wants to be part of the future that is video and in the same time make sure that videos that do not really follow your community code of conduct do not get included, video analysis feature allows you to know in a very short timeframe after posting video that it is OK to show it - or to tell you that it should be removed.

You can of course use it as a means of getting more data about the people on the video if you are recruitment service as it can give you details such as gender and alike from the video without the need for you to go over all of the videos - making it easy to just make corrections and updates to particular segments later on at your own convenience.

This is the code that we could use here:

//if we are after details detected on the frames of the video through our
// visual analysis feature the following would be of interest
$visual_data = $video_data['original_stream']['video_analysis'];

//they tell us the seconds in the video where something happened
$timestamps = $visual_data['timestamps'];
//this gives us types / classes of elements found. For example if you were
// recording yourself with white background it would say something like
// "portrait, {gender}, adult, facial expression, etc.
$classes = $visual_data['classes'];
//this gives you a score of each class expressed above
$scores = $visual_data['scores'];

As all of the above, this one can also be found on our GitHub pages here:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/_webhook_for_video_analysis.php

Hope that you enjoyed reading through this one as much as I making it and if you have any questions about this, please do let us know in the comments bellow. :)

EDIT [2019/11/20]: Changed the links to reflect our new file naming.

We suggest to check out our entire demo folder on Github to see many more demos:

https://github.com/Ziggeo/ZiggeoPhpSdk/blob/master/demos/