Ë
Glen Semino By Glen Semino • July 19, 2017

Tutorial: How to Add and Use Webhooks for Creating Custom Video Workflows

In a previous blog post we talked about how online video works and walked through a simple video workflow that involved uploading, transcoding and delivery. In this article, we will go beyond a simple video workflow and talk about how to create custom video workflows that can be built using SYNQ’s programmable webhooks technology.

Webhooks illustration

Situations that require a custom video workflow

To begin, let's discuss a few situations and give a few examples where one would need to have a custom workflow:

  • Analyze the contents of a video, either the content in the frames, the audio or both
  • Be alerted when a video object has changed states such as been uploaded or transcoded
  • Pull out additional metadata from an uploaded video
  • Do any type of post processing to an uploaded video
  • Integrate with another system, such as adding information about a transcoded video to one’s own database

Some examples that would require a custom video workflow and fit at least one of the above mentioned situations are:

  • You want the ability to detect that certain objects exist in a video and do something based on that information
  • You want to automatically turn the audio from a video into text to create closed captions
  • As soon as a video has been transcoded and is ready for playback, you want to add it to your database and make it ready for playback on your web and/or mobile application
  • You want to be notified via email when a video has been uploaded and also when it has completed the transcoding process

The above are simply some examples of what one can do with a custom video workflow, there are many more ideas or solutions one could create given the types of situations a custom video workflow can provide. Now that we know why you would want a custom video workflow and I have given some examples, let’s go to into how such a solution would be implemented.

Creating a custom video workflow

Now let’s say you want to create a custom video workflow that sends email notifications when a video is uploaded and also sends an email when a video is ready for embedding. To do this we will need the following:

  • We will use SYNQ’s programmable webhooks, this will let us interact with the video objects at different states, for this case we will need to interact with the video object after it has been uploaded and during the transcoding process
  • We will use Mailgun, an email service that offers Restful APIs, so that in our webhook we can send notification messages as HTTP Post requests

One of the first things we will need to do before creating the webhooks, is to understand how to send an HTTP Post request email message with Mailgun. These are the things we will need to know how to do, in order to send an email notification:

  • Send HTTP Post request with Mailgun that is authenticated with our Mailgun account
  • Know what are the minimum parameters we can send in our HTTP Post request to send an email message

Mailgun provides excellent documentation and examples for their API. To authenticate with Mailgun, all you need to do is use your Mailgun API key in your Mailgun API call. This is what the URL for an HTTP Post API call ends up looking like:

https://api:<your_api_key>@api.mailgun.net/v3/<your_email_domain>/messages

Simply modify <your_api_key> with the API key found in your account settings and modify <your_email_domain> with the domain you are using with your mailgun account.

Once you are able to authenticate with Mailgun. The next part is to have the parameters you need to send in your HTTP Post request to send an email. To send an email, Mailgun provides examples, such as this cURL example:

curl -s --user 'api:YOUR_API_KEY' \
    https://api.mailgun.net/v3/YOUR_DOMAIN_NAME/messages \
    -F from='Excited User <mailgun@YOUR_DOMAIN_NAME>' \
    -F to=YOU@YOUR_DOMAIN_NAME \
    -F to=bar@example.com \
    -F subject='Hello' \
    -F text='Testing some Mailgun awesomeness!'

 

From the cURL example, I was able to determine that to send an email message, all the parameters required were:

  • from - here we specify the email address the message will be coming from
  • to - here we specify the email address that we want to send the message to
  • subject - the subject of the email message
  • text - here we put any text we want to have in the body of the email message

Now that we know how to authenticate with Mailgun and the parameters needed to form a HTTP Post request, we are ready to start coding our webhook.  

Coding our programmable webhook

Within SYNQ’s programmable webhooks, there are 3 sections where you can add custom code that gets triggered by different video states, or changes in the video object as stated below:

  • on_video_create - runs code only when a video object is created
  • on_video_update - runs code anytime the video object is updated  

For this example, since we want to send a notification when a video is uploaded and when it is ready for embedding, you will need to put your code in the ‘on_video_update’ section of the programmable webhooks page.

To begin, you will need to login to your SYNQ Dashboard. Once you are logged in, click on the project name (where you want to have email notifications) to get into the settings page and then inside the settings page go to the ‘Programmable webhooks’ section. On the Programmable webhooks page you can add or modify code within the ‘on_video_update’ section as shown in the sequence of screenshots below:

Video webhook screenshot 1

Video webhook screenshot 2

Video webhook screenshot 3

Once we are in the on_video_update section of the Programmable Webhooks, we can modify the code inside the text box provided for code. A few things to remember:

  • In order to save any code you must click the ‘SAVE’ button found at the bottom of the terminal window
  • In order to activate our webhook you must slide the ‘Active’ slider to the right once you are ready
  • Your function declaration for the ‘on_video_update’ webhook must be this: function on_video_update(oldVideo, newVideo)
  • The code you write inside the webhook will be JavaScript

Now we are finally ready to start writing code. The on_video_update webhook keeps track of changes from one video state to another by using two objects called ‘oldVideo’ and ‘newVideo’. Therefore we need to do comparisons between the old and the updated video object to be able to capture state changes.

We want to send one notification when a video object state changes to uploaded. This is what our if-statement ends up looking like:

if (oldVideo.state != 'uploaded' && newVideo.state == 'uploaded')

 

The above if-statement will be executed only if the current video state of one video object is ‘uploaded’ and the previous video state was not already ‘uploaded’. Next we must also save our Mailgun URL from earlier in a variable like this:

mailgun_uri =
 https://api:<your_api_key>@api.mailgun.net/v3/<your_mailgun_domain>/messages';

 

Lastly for the body of your if-statement, you need to set the parameters for your HTTP Post request and encode them, so that they send properly. For making sure things are encoded properly JavaScript provides a function called encodeURI, we will wrap our parameters around the encodeURI function. The result is this:

r_body = encodeURI("from=mailgun@<your_domain_name>&to=<email_you_want_send_to>&subject=Video Uploaded&text=A video has been uploaded! Video id is: " + newVideo.video_id);

 

Last part is we need to put our Mailgun URL and parameters into an HTTP Post request. When putting everything together we get:

function on_video_update(oldVideo, newVideo) {
  mailgun_uri = '<your_api_key>@api.mailgun.net/v3/<your_mailgun_domain>/messages';  
  //email notification will be sent when a video has been uploaded
  if (oldVideo.state != 'uploaded' && newVideo.state == 'uploaded') {
      r_body = encodeURI("from=mailgun@<your_domain_name>&to=<email_to_send_to>&subject=Video Uploaded&text=A video has been uploaded! Video id is: " + newVideo.video_id);   
      v1.http.POST({
          "url": mailgun_uri,    
          "rawBody": r_body      
      }); 
  }
}

 

To test this, make sure you saved your code and slid the slider to the right to make the hook active. From there, all you need to do is upload a video and make sure the email notification was sent to the email address you provided in the ‘to’ parameter in your HTTP Post request. The email notification should look something like this:

Webhook Gmail screenshot 1

Assuming the above worked for you, we are now ready to create the second email notification.

Most of the code will be very similar to the first notification we just created. The only real difference is our if-statement and the text we send in our HTTP Post request. For a video to be ready for embedding, one of the transcoded outputs needs to be available, since this indicates we have an output that is playable. Thus, for our if-statement we can choose to check when one of the outputs is present and know that the video is ready for embedding. The results look like this:

if(oldVideo.get("outputs.mp4_360.state") != "complete" && newVideo.get("outputs.mp4_360.state") == "complete"

 

In the code example above, we check that in the old state, the 360p output was not complete and in the new/current state, the 360p output is complete. Thus, we can ensure that while the video updates, we will only get notified once and only when the 360p output is complete. Beyond that, we only change the text in our email parameters and this is the result when putting it all together (including the first notification):

function on_video_update(oldVideo, newVideo) {
  mailgun_uri = 'https://api:<your_api_key>@api.mailgun.net/v3/<your_mailgun_domain>/messages';  
  //email notification will be sent when a video has been uploaded
  if (oldVideo.state != 'uploaded' && newVideo.state == 'uploaded') {
      r_body = encodeURI("from=mailgun@<your_domain>&to=<email_to_send_to>&subject=Video Uploaded&text=A video has been uploaded! Video id is: " + newVideo.video_id);   
      v1.http.POST({
          "url": mailgun_uri,    
          "rawBody": r_body      
      }); 
  }
  
  //email notification  will be sent when video is ready for playback
  if(oldVideo.get("outputs.mp4_360.state") != "complete" && newVideo.get("outputs.mp4_360.state") == "complete"){
      embed_url = newVideo.get("player.embed_url");
      r_body = encodeURI("from=mailgun@<your_domain>&to=<email_to_send_to>&subject=Video Ready&text=Video has completed! Video playback URL is: " + embed_url);   
      v1.http.POST({
          "url": mailgun_uri,    
          "rawBody": r_body      
      }); 
  }
}

 

You can test the same way as previously, this time you should expect to get two email notifications; one for when the video is uploaded and one for when the video is ready for embedding:

Video webhook Gmail screenshot 2

The email notification for the second notification should look something like this:

Video webhook Gmail screenshot 3

We have now created a notification system that will email us everytime a video is uploaded and also provide us an embed URL as soon as the video is ready for playback. You can further build on this by having the emails go to another system that then does further processing on the notifications or create other types of custom video workflows using similar types of steps.

What's next?

We have now discussed custom video workflows and seen an example of what can be created. The possibilities of the types of video solutions that can be created are endless and SYNQ simplifies the process by providing a simple video workflow and allowing one to build on that using programmable webhooks. With that in mind hopefully you have now been inspired to build the next big thing in video!


Sign up for free and start incorporating video in your web or mobile solution today:

GET YOUR FREE API KEY


 

Related posts: