How to Use Webhooks for Your Live Stream

January 25, 2022 by
 

Webhooks are a powerful tool used in video streaming that can save you a significant amount of time and resources. If you’re not currently using webhooks and wondering if you should be, webhooks alert you when an event has occurred and eliminate the need to repeatedly query the API for that same information. With an API, you ask for new data through a process known as “polling,” but constantly polling the API can be wasteful since it requires a certain amount of code and bandwidth. Instead, you can conserve resources by creating a webhook notification system and allow Wowza Streaming Cloud to instantly alert you when an event has taken place.

Here’s a simple example:

You need to know when a stream recording has finished uploading and is available for playback. Rather than polling the API for an update, a webhook notification system will alert you the instant that recording has successfully processed and is ready. In addition, webhook notifications alert you to events that are undesirable and allow you to quickly troubleshoot. For example, you may receive a notification that a stream recording has failed, allowing you to quickly troubleshoot the issue.

If you’re new to webhooks, keep in mind they can only notify you about an event that has happened, so there will be times when it will still be necessary to use an API. For example, if you want to make a change to your video stream, you’ll need to use an API. It’s also possible a webhook notification may not contain all the data you need about an event, but a specific API call could. Overall, webhooks are still your best bet for the real-time transfer of stream data and can save you a lot of time and work.

 Configuring a webhook alert system for testing is simple. These are the basic steps:

  1. Create a webhook endpoint and unique URL.
  2. Enter that URL in the webhook section of Wowza Streaming Cloud Manager.
  3. Choose the type of events you want to be notified about.

In this case, the webhook endpoint is the destination to which Wowza Streaming Cloud sends the notifications. When we configure webhooks, we instruct Streaming Cloud to send the notifications to a unique URL — which will be further explained in the steps below.

 

Create a Webhook Notification System

To receive event notifications, you first need to enable webhooks for your Streaming Cloud account and create a webhook endpoint to receive the notifications.

 

A. Create a Webhook Endpoint

Your webhook endpoint will have an associated public URL that Wowza Streaming Cloud can send notifications to. In this tutorial, we will use the webhook listener http://webhook.site which generates a free, unique URL for testing.

1. Open http://webhook.site. You do not need to create a paid account for testing.

2. Locate the unique URL provided on the home page. You will copy and paste this in Streaming Cloud in a future step.

A screenshot showing a unique webhook URL generated in https://webhook.site/

3. You’ll also be provided with a unique email address for the endpoint that you may want to save for future reference.

4. The webhooks.site homepage will display a message in the left navigation pane stating it is “Waiting for the first request.” This means it’s now listening for an event notification from Streaming Cloud, so we’re ready to enable webhooks in our Cloud account.

 

B. Enable Webhooks in Streaming Cloud

1. Log into Wowza Streaming Cloud, click the dropdown arrow next to your username in the menu bar, and then select Account Settings.

2. On the Integrations page, click the Enable tab for Webhook.

A screenshot of the integration page in Wowza Streaming Cloud.

3. Next, you must check the Enabled box.

Another screenshot of the integration page in Wowza Streaming Cloud for enabling Webhooks.

4. In the Unique URL field, enter the URL you want the webhook notifications sent to. This is the URL for the webhook endpoint you created in Section A above.

5. (Optional) Select Use Basic Authentication if your webhook endpoint requires authentication for POST requests, and then enter the username and password required by your endpoint.

If you select this option, make sure your webhook endpoint is configured to authenticate because Wowza Streaming Cloud sends basic authentication credentials in the Authorization header.

 

Webhook Payloads

When Streaming Cloud sends a notification that an event has occurred to your endpoint, we refer to that as the webhook payload. Let’s look at an example of what that looks like when a transcoder has stopped.

 

Sample webhook payload

{
  "version": 1.0,
  "event": "stop.complete",
  "event_id": "9be47e2a-b5ff-492a-a291-c7be79c060ba",
  "event_time": 1588864470.813283,
  "object_type": "transcoder",
  "object_id": "pl3fff7q",
  "object_data": {
    "uptime_id": 7cb5yfnx
  }
}
 

The structure of the webhook is the same for each event triggered, but the information provided in fields changes depending on the event triggered and the object that triggered it. In the JSON response above, the list of keys listed are called the webhook envelope and each envelope key is followed by its specific value.

 
Envelope keyDescription
versionThe version of the Wowza webhook envelope.
EventThe event triggered by the object. See the Transcoder and live stream and Recording tables for a complete list of events.
Event_idThe unique ID that identifies the specific instance of this event. You can use this ID for internal tracking uses you might have or when you interact with Wowza support to troubleshoot issues.
Event_timeThe time, in Unix epoch format, that the event was triggered in Wowza’s webhook system.
Object_typeType of object that triggered the event. Valid values are transcoder or recording.
Object_idThe unique ID of the object that triggered the event. For transcoders, the object_id is the transcoder ID. For recordings, the object_id is the recording ID. You can use these IDs to locate the object that triggered the event in Wowza Streaming Cloud.
Object_dataData relevant to the object and event that triggered the webhook.
 

After you’ve created the webhook endpoint and enabled webhooks in Streaming Cloud, it might be helpful to know the following:

 

Transcoder Events

Wowza Streaming Cloud sends event notifications for transcoder actions. The object_id in the webhook payload is the transcoder ID.

Note: These events are triggered for transcoder actions in both the live stream and transcoder workflows.

Several types of notifications can be sent for transcoder events. In the example below, we see a payload example when a transcoder has started to successfully receive video data.

 
Event Sample Payload Description
video.started
{
  "version":"1.0",
  "event":"video.started",
  "event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "stream_name": "3920b4c6.stream",
    "height": "720",
    "width": "1280",
    "codec": "H264",
    "codec_string": "avc1.4d402a",
    "profile": "Main",
    "level": "1.2",
    "reference_id": "null"
}
Occurs when a running transcoder has started receiving video.
   

You may notice at the bottom of the payload response that the reference_id is null. If you’d like to assign your own specific reference ID, Version 1.7 of the Wowza Streaming Cloud API introduces functionality that allows you to do so in the object data section of the JSON response body. For example, if you’d like your reference id to be mySystemID_01, this is where you would assign that specific name.

Sample data_object after setting reference_id:

"object_data": {
    "uptime_id": "jbfg6npg",
    "reference_id": "mySystemID_01"
  }

See POST /transcodersPATCH /transcoders/[ID]POST /live_streams, and PATCH /live_streams/[ID] for more information.

 

Recording Events

Wowza Streaming Cloud sends webhook notifications for recording activity. The object_id in the payload is the recording ID. As mentioned earlier, event notifications can be beneficial when an expected streaming action was unsuccessful.

The complete list of recording event notifications can be found here, but let’s examine the payload response for a failed recording.

 
Event Sample Payload Description
failed
{
  "version":"1.0",
  "event":"failed",
  "event_id":"nxf71a9c-5716-4a91-8179-8a0e131fd8b0",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id": "b3hjs7ty",
    "transcoder_uptime_id": "blc5grjh",
    "reason_code": "recording_too_long",
    "reason": "Recording Convert Failing: 
been running over 45 minutes 
(45.31778333333333 mins) and file size is 
still 0, aborting recording for 
wse_recording_id: 31255, transcoder id 
397800",
}
Occurs when a recording failed to be converted or uploaded. object_data includes a reason_code and a descriptive reason string for the failure.   If the file couldn’t be converted to an mp4, the reason_code can be either of the following:  
  • conversion_failed
  • recording_too_long
If the mp4 is corrupt, the reason_code can be either of the following:  
  • invalid_mp4
  • invalid_mp4_stsd
Note: stsd = sample description box
 

Notice that in addition to a reason code, the payload provides a detailed reason why the recording failed for more accurate and effective troubleshooting.

 

Webhooks and Troubleshooting

In summary, webhooks instantly alert you to events as they occur in your Streaming Cloud account, including operations that didn’t perform as expected. Because webhooks are meant to only push an event alert to you, they may not always provide the extra details required for troubleshooting. In these situations, there are a few steps you can take to try and correct an issue or gather more information:

 

Conclusion

Configuring webhooks in Wowza Streaming Cloud can automate and streamline your workflows. This tutorial was a simple demonstration of how you can test with webhook notifications, but it is possible to create an advanced webhook notification system directly linked to the Streaming Cloud REST API. This would enable your application to respond to the notifications as they are received for workflows that have more specific needs. If you’d like some help creating a more advanced webhook system, the experts on Wowza’s Professional Services team can quickly deploy this for you.

 

Additional Resources:

For more information on how to configure Webhooks in Streaming Cloud, check out our documentation.

If you do not have a Wowza Streaming Cloud account, we offer a free 30-day trial with no credit card or obligation. You can also purchase a license here.  For those of you who are currently Wowza Streaming Engine customers and are curious if migrating to Wowza Streaming Cloud may be right for you, we’re offering a free one-hour technical consultation with a solutions engineer to evaluate your workflows.

 

About Rose Power

Rose Power is the developer community manager for Wowza Media Systems. Passionate about building relationships with the dev community, Rose strives to deliver quality resources for a positive user experience built on trust. When not working, she can be found… View more