Learn how to Use Webhooks for Your Dwell Stream
By Hepisoping Webhooks are a strong software utilized in video streaming that may prevent a major period of time and assets. In the event you’re not presently utilizing webhooks and questioning if you have to be, webhooks warn you when an occasion has occurred and remove the necessity to repeatedly question the API for that very same data. With an API, you ask for brand spanking new knowledge by way of a course of generally known as “polling,” however continuously polling the API might be wasteful because it requires a specific amount of code and bandwidth. As an alternative, you’ll be able to preserve assets by making a webhook notification system and permit Wowza Streaming Cloud to immediately warn you when an occasion has taken place.
Right here’s a easy instance:
You’ll want to know when a stream recording has completed importing and is out there for playback. Relatively than polling the API for an replace, a webhook notification system will warn you the moment that recording has efficiently processed and is prepared. As well as, webhook notifications warn you to occasions which can be undesirable and permit you to rapidly troubleshoot. For instance, you might obtain a notification {that a} stream recording has failed, permitting you to rapidly troubleshoot the problem.
In the event you’re new to webhooks, be mindful they’ll solely notify you about an occasion that has occurred, so there might be instances when it would nonetheless be needed to make use of an API. For instance, if you wish to make a change to your video stream, you’ll want to make use of an API. It’s additionally attainable a webhook notification might not comprise all the info you want about an occasion, however a selected API name might. General, webhooks are nonetheless your finest guess for the real-time switch of stream knowledge and might prevent plenty of time and work.
Configuring a webhook alert system for testing is easy. These are the fundamental steps:
- Create a webhook endpoint and distinctive URL.
- Enter that URL within the webhook part of Wowza Streaming Cloud Supervisor.
- Select the kind of occasions you need to be notified about.
On this case, the webhook endpoint is the vacation spot to which Wowza Streaming Cloud sends the notifications. Once we configure webhooks, we instruct Streaming Cloud to ship the notifications to a singular URL — which might be additional defined within the steps under.
Create a Webhook Notification System
To obtain occasion notifications, you first have to allow webhooks to your Streaming Cloud account and create a webhook endpoint to obtain the notifications.
A. Create a Webhook Endpoint
Your webhook endpoint could have an related public URL that Wowza Streaming Cloud can ship notifications to. On this tutorial, we are going to use the webhook listener http://webhook.web site which generates a free, distinctive URL for testing.
1. Open http://webhook.web site. You do not want to create a paid account for testing.
2. Find the distinctive URL offered on the house web page. You’ll copy and paste this in Streaming Cloud in a future step.
3. You’ll even be supplied with a singular e mail deal with for the endpoint that you could be need to save for future reference.
4. The webhooks.web site homepage will show a message within the left navigation pane stating it’s “Ready for the primary request.” This implies it’s now listening for an occasion notification from Streaming Cloud, so we’re able to allow webhooks in our Cloud account.
B. Allow Webhooks in Streaming Cloud
1. Log into Wowza Streaming Cloud, click on the dropdown arrow subsequent to your username within the menu bar, after which choose Account Settings.
2. On the Integrations web page, click on the Allow tab for Webhook.
3. Subsequent, you have to test the Enabled field.
4. Within the Distinctive URL discipline, enter the URL you need the webhook notifications despatched to. That is the URL for the webhook endpoint you created in Part A above.
5. (Optionally available) Choose Use Primary Authentication in case your webhook endpoint requires authentication for POST requests, after which enter the username and password required by your endpoint.
If you choose this selection, be certain your webhook endpoint is configured to authenticate as a result of Wowza Streaming Cloud sends fundamental authentication credentials within the Authorization header.
Webhook Payloads
When Streaming Cloud sends a notification that an occasion has occurred to your endpoint, we confer with that because the webhook payload. Let’s have a look at an instance of what that appears like when a transcoder has stopped.
Pattern webhook payload
{
"model": 1.0,
"occasion": "cease.full",
"event_id": "9be47e2a-b5ff-492a-a291-c7be79c060ba",
"event_time": 1588864470.813283,
"object_type": "transcoder",
"object_id": "pl3fff7q",
"object_data": {
"uptime_id": 7cb5yfnx
}
}
The construction of the webhook is identical for every occasion triggered, however the data offered in fields modifications relying on the occasion triggered and the item that triggered it. Within the JSON response above, the checklist of keys listed are referred to as the webhook envelope and every envelope key’s adopted by its particular worth.
After you’ve created the webhook endpoint and enabled webhooks in Streaming Cloud, it is perhaps useful to know the next:
- If in case you have an ID in your streaming utility that you simply need to affiliate with Streaming Cloud transcoder occasions and have returned within the transcoder webhook payloads, use the Wowza Streaming Cloud REST API to set the reference_id.
- See POST /transcoders, PATCH /transcoders/[ID], POST /live_streams, and PATCH /live_streams/[ID] for extra data.
Transcoder Occasions
Wowza Streaming Cloud sends occasion notifications for transcoder actions. The object_id within the webhook payload is the transcoder ID.
Word: These occasions are triggered for transcoder actions in each the dwell stream and transcoder workflows.
A number of varieties of notifications might be despatched for transcoder occasions. Within the instance under, we see a payload instance when a transcoder has began to efficiently obtain video knowledge.
| Occasion | Pattern Payload | Description |
| video.began |
{
"model":"1.0",
"occasion":"video.began",
"event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
"event_time":1621437110.6554534,
"object_type":"transcoder",
"object_id":"vxbfbxwv",
"object_data":{
"stream_name": "3920b4c6.stream",
"top": "720",
"width": "1280",
"codec": "H264",
"codec_string": "avc1.4d402a",
"profile": "Essential",
"stage": "1.2",
"reference_id": "null"
}
|
Happens when a operating transcoder has began receiving video. |
You could discover on the backside of the payload response that the reference_id is null. In the event you’d wish to assign your individual particular reference ID, Model 1.7 of the Wowza Streaming Cloud API introduces performance that enables you to take action within the object knowledge part of the JSON response physique. For instance, if you happen to’d like your reference id to be mySystemID_01, that is the place you’d assign that particular title.
Pattern 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 extra data.
Recording Occasions
Wowza Streaming Cloud sends webhook notifications for recording exercise. The object_id within the payload is the recording ID. As talked about earlier, occasion notifications might be useful when an anticipated streaming motion was unsuccessful.
The whole checklist of recording occasion notifications might be discovered right here, however let’s study the payload response for a failed recording.
| Occasion | Pattern Payload | Description |
| failed |
{
"model":"1.0",
"occasion":"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",
"motive": "Recording Convert Failing:
been operating over 45 minutes
(45.31778333333333 minutes) and file measurement is
nonetheless 0, aborting recording for
wse_recording_id: 31255, transcoder id
397800",
}
|
Happens when a recording did not be transformed or uploaded. object_data features a reason_code and a descriptive motive string for the failure.
If the file couldn’t be transformed to an mp4, the reason_code might be both of the next:
If the mp4 is corrupt, the reason_code might be both of the next:
Word: stsd = pattern description field |
Discover that along with a motive code, the payload gives an in depth motive why the recording failed for extra correct and efficient troubleshooting.
Webhooks and Troubleshooting
In abstract, webhooks immediately warn you to occasions as they happen in your Streaming Cloud account, together with operations that didn’t carry out as anticipated. As a result of webhooks are supposed to solely push an occasion alert to you, they could not all the time present the additional particulars required for troubleshooting. In these conditions, there are a couple of steps you’ll be able to take to attempt to appropriate a difficulty or collect extra data:
- Assessment the logs
- Restart the Streaming Cloud Transcoder
- Use the Streaming Cloud REST API to acquire further knowledge
Conclusion
Configuring webhooks in Wowza Streaming Cloud can automate and streamline your workflows. This tutorial was a easy demonstration of how one can take a look at with webhook notifications, however it’s attainable to create a sophisticated webhook notification system immediately linked to the Streaming Cloud REST API. This may allow your utility to answer the notifications as they’re acquired for workflows which have extra particular wants. In the event you’d like some assist making a extra superior webhook system, the consultants on Wowza’s Skilled Providers staff can rapidly deploy this for you.
Further Assets:
For extra data on easy methods to configure Webhooks in Streaming Cloud, take a look at our documentation.
In the event you wouldn’t have a Wowza Streaming Cloud account, we provide a free 30-day trial with no bank card or obligation. You may also buy a license right here. For these of you who’re presently Wowza Streaming Engine clients and are curious if migrating to Wowza Streaming Cloud could also be best for you, we’re providing a free one-hour technical session with a options engineer to judge your workflows.
Get Ideas and Methods Delivered to Your Inbox
Subscribe to Weblog
Further Assets
- Obtain Wowza Streaming Cloud Occasion Notifications With Webhooks
- Wowza Streaming Cloud Occasion Reference Documentation
About Rose Energy
Rose Energy is the developer neighborhood supervisor for Wowza Media Methods. Enthusiastic about constructing relationships with the dev neighborhood, Rose strives to ship high quality assets for a optimistic person expertise constructed on belief. When not working, she might be discovered… View extra
