How to Use Webhooks for Your Live Stream

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 Video 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 the Wowza Video dashoard.
3. Choose the type of events you want to be notified about.

In this case, the webhook endpoint is the destination to which Wowza Video sends the notifications. When we configure webhooks, we instruct Wowza Video 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 Wowza Video 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 Video 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 Wowza Video in a future step.

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 Wowza Video, so we’re ready to enable webhooks in our account.

B. Enable Webhooks in Wowza Video

1. Log into Wowza Video, 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 to open the Webhooks page.

3. Next, you must check the Enabled box.

4. In the Your Webhook 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 Video sends basic authentication credentials in the Authorization header.

Webhook Payloads

When Wowza Video 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.

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

• If you have an ID in your streaming application that you want to associate with Wowza Video transcoder events and have returned in the transcoder webhook payloads, use the Wowza Video REST API to set the reference_id.
• See POST /transcoders, PATCH /transcoders/[ID], POST /live_streams, and PATCH /live_streams/[ID] for more information.

Transcoder Events

Wowza Video 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.

{
  "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"
}

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 Video 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 /transcoders, PATCH /transcoders/[ID], POST /live_streams, and PATCH /live_streams/[ID] for more information.

Recording Events

Wowza Video 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.

{
  "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",
}

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 Wowza Video 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:

• Review the logs
• Restart the Wowza Video Transcoder
• Use the Wowza Video REST API to obtain additional data

Conclusion

Configuring webhooks in Wowza Video 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 Wowza Video 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 Wowza Video, check out our documentation.

If you do not have a Wowza Video 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 Video may be right for you, we’re offering a free one-hour technical consultation with a solutions engineer to evaluate your workflows.