Dispersa alerts API

WMSPanel team continues improving Dispersa streams availability monitoring service. After introducing streams monitoring history, we wanted to make Dispersa be more flexible in terms of notification capabilities. As example, people would may want to re-set a stream if it's not visible to the checkpoints, or just send several messages to end-users who use WMSPanel via white label.

Today we introduce push API for Dispersa check-over events. You may now get calls to your handler application from our service when any of your streams are unavailable or available back online again.

Here's how it works.

1. Set up streams to monitor

Use this instruction to set up streams which you'd like to monitor via Dispersa distributed network of checkpoints.

2. Create a handler

A handler is a publicly available web application which can get HTTP POST requests. This might be implemented using any programming technology. Check this example from our streams un-publish notifications for Wowza for to see how this can be done via PHP with PECL packages installed.

3. Set up handler URL in WMSPanel

Now log into WMSPanel and choose Control / API set up menu. Then select Notifications API tab.

Dispersa notifications push API setup page.

Here you need to enter the URL of your handler and check Send Dispersa stream offline events checkbox. Clicking on Save button you will initiate the monitoring notifications process.

If you'd like to authenticate WMSPanel alerts, you need to get a generated token to use it on step 4.

4. Process status notifications

When any of the streams becomes unavailable or gets online, Dispersa will call handler and post a JSON data containing time of event, a digest (signature), stream full URL, its status and names of checkpoints which failed the check-over.

Here's an example:

{"time":"2014-10-16 03:13:31 UTC","digest":"d93053a1875c034384bb4fb06b20792f","stream":"rtmp://example.com/monitored/stream","status":"offline", "checkpoints": ["New York, USA", "Private Checkpoint"]
}

A status may be "online" and "offline".

A digest is a signature which you may compare on your side by calculating it as "MD5(time + token)", where "time" is the time of receiving the message and "token" is the string which you see in API setup page. It can be used to check the credibility of incoming request.

That's it. You may now create your events' handler to take actions on streams behavior, to notify your users or just collect your own statistics for internal usage. If you'd like to share your ideas about Dispersa improvements, just let us know about it.

If you want to control Dispersa streams dynamically, check Dispersa monitoring API.

Related documentation

Dispersa streams monitoring, WMSPanel API reference, How to set up streams availability monitoring, Streams monitoring history, Adding private checkpoints for Dispersa, Allowing Dispersa to check WMSAuth protected streams, Server offline notifications API, End user reporting for media servers