Use webhooks to listen for and respond to events in your Wowza Video account.
In the latest version of Wowza Video, we've introduced new webhooks with enhanced functionality, including events like video events.
If you currently use webhooks in the legacy version of Wowza Video and plan to upgrade, please note that you must create new webhooks after migrating to the latest version. The existing webhooks from the legacy system will not carry over automatically.
For more information, see Webhooks event reference and Receive webhooks notifications in Wowza Video.
To receive event notifications, you have to enable webhooks for your account and create a webhook endpoint. See Receive event notifications with webhooks for more information.
This topic only applies to version 1.x of the REST API and the Wowza Video Legacy user interface.
Wowza Video sends webhook events for transcoder and recording actions in JSON format through a POST request. The following sample webhook payload is sent when a transcoder stops.
{ "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 envelope, or structure, of the webhook is the same for each event triggered, but the information provided in the envelope fields change depending on the event triggered and the object that triggered it.
| 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. |
Wowza Video sends the following events for transcoder actions. The object_id in the payload is the transcoder ID.
These events are triggered for transcoder actions in both the live stream and transcoder workflows.
The tables below list the event names and sample payloads for each webhook in both the Wowza Video Legacy and the new Wowza Video experience. This comparison will help you identify which new webhooks to use after upgrading to the new Wowza Video experience.
| Event name in Wowza Video Legacy | Sample payload in Wowza Video Legacy | Event name in the new Wowza Video experience | New sample payload in the new Wowza Video experience | Description |
|---|---|---|---|---|
| download.success | { | Not available | Not available | Occurs when the transcoder successfully downloads the source file. Only applicable when a file is the source for a stream. |
| download.failed | { | Not available | Not available | Occurs when the URL in file_name returns a 404 error and the file can't be downloaded. Only applicable when a file is the source for a stream. |
| start.requested | { | transcoder.start.requested | { | Occurs when a request is made to start a transcoder. |
| start.complete | { | transcoder.start.complete | { | Occurs when the transcoder starts and is available. |
| start.canceled | { | transcoder.canceled | { | Occurs when the transcoder cancels the startup process because of a failure. |
| reset.requested | { | Not available | Not available | Occurs when a request is made to reset a transcoder. |
| stop.complete | { | transcoder.stop.complete | { | Occurs when the transcoder has stopped and is no longer available. |
| audio.started | { | transcoder.audio.started | { | Occurs when a running transcoder has started receiving audio. |
| audio.stopped | { | transcoder.audio.stopped | { | Occurs when a running transcoder has stopped receiving audio. |
| video.started | { | transcoder.video.started | { | Occurs when a running transcoder has started receiving video. |
| video.stopped | { | transcoder.video.stopped | { | Occurs when a running transcoder has stopped receiving video. |
By default, reference_id is null. Version 1.7 of the Wowza Video API introduces functionality that lets you set a unique ID, reference_id, associated with transcoder events and returned in transcoder webhook payloads.
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.
Wowza Video sends the following events for recording actions. The object_id in the payload is the recording ID.
| Event name in Wowza Video Legacy | Sample payload in Wowza Video Legacy | Event name in the new Wowza Video experience | New sample payload in the new Wowza Video experience | Description |
|---|---|---|---|---|
| converting | { | Not available | Not available | Occurs when a recording has been created and conversion to mp4 format begins. |
| uploading | { | Not available | Not available | Occurs when a recording is being uploaded to account storage. |
| completed | { | Not available | Not available | Occurs when a recording is complete and available in account storage. |
| failed | { | Not available | Not available | 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:
If the mp4 is corrupt, the reason_code can be either of the following:
|
| no_video | { | Not available | Not available | Occurs when no video content is found for the recording. |
| deleted | { | Not available | Not available | Occurs when a recording is deleted.
Note:uptime_id is deprecated. Use transcoder_uptime_id instead. |
Wowza Video sends the following events for real-time streams. The object_id in the payload is the real-time stream ID.
| Event name in Wowza Video Legacy | Sample payload in Wowza Video Legacy | Event name in the new Wowza Video experience | New sample payload in the new Wowza Video experience | Description |
|---|---|---|---|---|
| video.started | { | real_time_stream.started | { | Occurs when a real-time stream has started streaming. |
| video.stopped | { | real_time_stream.stopped | { | Occurs when a real-time stream has stopped streaming. |