March 26, 2013

Notifying on publish and un-publish RTMP Wowza streams

WMSPanel agent works closely with Wowza server so we literally feel its pulse. That's why one of the first features was server offline/online notification. Moving forward we got requests from customers asking for the same for incoming RTMP streams monitoring. Basically people need to know when the stream becomes un-available and get notified about that.

Having been notified about RTMP publish or unpublish event, we can inform a customer about the failure or recover. This kind of events may happen very often, especially if you have thousands of streams. That's why using email is inappropriate in this case.

That's why we implemented this as a push API.

If you want to use the notifications API, the major steps for starting using this are as follows:
  1. Create a processing script on your web site and check its availability.
  2. Add a processing script URL in WMSPanel.
  3. Test the solution.
Having those steps complete, you'll have the script is automatically called each time our agent gets publish or un-publish event from all servers registered in WMSPanel.

Let's go step by step to see what you need to do.

1. Create a processing script


Agent uses POST request to call your URL. Your script MUST get request body first.
Request body will looks like this(without formatting of course):
{"ApiSyncRequest": {"ID": "1111-222-333-444,
                                 "Signature": "PD94bWwgdmVyc2lvbj0iMS4wIiBlbmNvZGluZz0iVVRGLTg",
                                 "Puzzle": "42342-33434-343434-34343",
                                 "Publish": {
                                     "VHostName": "_defaultVHost_",
                                     "AppName": "live",
                                     "AppInstanceName": "_default_",
                                     "StreamName": "stream.stream"
                                  }
                                }
}

Signature is what your script MAY check to make sure that is was WMSPanel agent who sent it.

Signature = BASE64(MD5(ID + Puzzle + Token))
Your script response MUST be:
{"ApiSyncResponse": {"Solution": "PjxTZXJ2ZXJBdXRob3JpemF0aW9uUHJvcGVydGllcz48U2Vydm"}}

Solution param is checked by WMSPanel agent to make sure your script knows the token.

Solution = BASE64(MD5(Puzzle + Token))

You can find a small PHP sample of processing the incoming request in out github samples repo. Please also check full XSD for agent request.

2. Set up API in WMSPanel


Go to Control / API Settings and choose Push API tab.

Setting up API handler for unpublish/publish notifications.

Here define the following:
  1. Enter handler URL into Streams (un)publish handler URL field;
  2. Click on Send publish/unpublish notifications;
  3. Select Request format or leave default "JSON" value;
  4. Enter Sync interval or leave default 30 seconds.

A few seconds after you click on Save, the first sync-up will be sent to your handler.

API parameters also include Token field as well as Enable mutual authorization check box. Those should be used to extra security of data transfer and it's a subject for future separate article.

3. Test the complete solution


So now you can set up a testing stream (or use existing one) and then publish it to get notified by the panel via the script. In the given example you'll have new log entry.

This option will work perfectly with Wowza streams control functionality already available in WMSPanel.

Please also check full WMSPanel API reference for other API methods including statistics export.

3 comments:

  1. Do you guys have a more direct sample of how to implement the script into a PHP page? Like how you have concise sample code for the WMSAuth system.. Thanks!

    ReplyDelete
    Replies
    1. As I mentioned, the post is updated with the link to a new samples repo: https://github.com/WMSPanel/wmspanel-api-samples

      Please use stream-un-publish-notify.php as a very basic sample.

      Please kindly let us know if you make any improvements to it so we could share to the wider audience.

      Delete
  2. Yes, we'll provide some PHP sample soon in this post. It will be uploaded to our github account: https://github.com/WMSPanel.

    Meanwhile please drop an email to sales so we could inform you about it and check your account's API settings.

    Thanks for your interest!

    ReplyDelete