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:
- Create a webhook endpoint and unique URL.
- Enter that URL in the webhook section of the Wowza Video dashoard.
- 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.
-
Open http://webhook.site. You do not need to create a paid account for testing.
-
Locate the unique URL provided on the home page. You will copy and paste this in Wowza Video in a future step.
-
You’ll also be provided with a unique email address for the endpoint that you may want to save for future reference.
-
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
- Log into Wowza Video, click the dropdown arrow next to your username in the menu bar, and then select Account Settings .
- On the Integrations page, click the Enable to open the Webhooks page.
- Next, you must check the Enabled box.
-
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.
-
(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.
| Envelope key | Description |
|---|---|
| version | The version of the Wowza webhook envelope. |
| event | The event triggered by the object. See the Transcoder and live stream and Recording tables for a complete list of events. |
| event_id | The 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_time | The time, in Unix epoch format, that the event was triggered in Wowza’s webhook system. |
| object_type | Type of object that triggered the event. Valid values are transcoder or recording. |
| object_id | The 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 Video. |
| object_data | Data relevant to the object and event that triggered the webhook. |
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.
| 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 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.
| 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 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.