Wowza Video webhook event reference documentation

Use webhooks to listen for and respond to events in your Wowza Video account.

Info
  • 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.

Info

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.

Info

This topic only applies to version 1.x of the REST API and the Wowza Video Legacy user interface.

Events

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.

Copy
Copied
{
  "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.

Transcoder and live stream

Wowza Video sends the following events for transcoder actions. The object_id in the payload is the transcoder ID.

Info

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

{
  "version":"1.0",
  "event":"download.success",
  "event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "file_name":"https://download_url.mp4",
    "file_size":"58958409",
    "reference_id":"null"
}

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

{
  "version":"1.0",
  "event":"download.failed",
  "event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
     "file_name":"https://download_url.mp4",
     "file_size":"0",
     "reference_id":"null"
}

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

{
  "version":"1.0",
  "event":"start.requested",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":1621437043.201932,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "uptime_id":"vbbywpbz",
    "reference_id":"null"
}

 transcoder.start.requested

{
  "version":"2.0",
  "event_type":"transcoder.start.requested",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "uptime_id":"vbbywpbz",
    "reference_id":"null"
}

 Occurs when a request is made to start a transcoder.
start.complete

{
  "version":"1.0",
  "event":"start.complete",
  "event_id":"e2a3c832-ac5d-41b5-9453-d60ff14e5012",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "uptime_id":"bjwbhwld",
    "ip_address":"34.73.51.79",
    "reference_id":"null"
}

 transcoder.start.complete

{
  "version":"2.0",
  "event_type":"transcoder.start.complete",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "uptime_id":"vbbywpbz",
    "ip_address":34.73.51.79,
    "reference_id":"null"
}

 Occurs when the transcoder starts and is available.
start.canceled

{
  "version":"1.0",
  "event":"start.canceled",
  "event_id":"d1e3e732-ac5d-41b5-9453-d60ff14e5033",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "uptime_id":"null",
    "reference_id":"null"
}

 transcoder.canceled

{
  "version":"2.0",
  "event_type":"transcoder.canceled",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "uptime_id":"vbbywpbz",
    "ip_address":34.73.51.79,
    "reference_id":"null"
}

 Occurs when the transcoder cancels the startup process because of a failure.
reset.requested

{
  "version":"1.0",
  "event":"reset.requested",
  "event_id":"a3n3e832-ac5d-41b5-9453-d60ff14e5321",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "uptime_id":"null",
    "ip_address":"34.73.51.79",
    "reference_id":"null"
}

 Not available Not available Occurs when a request is made to reset a transcoder.
stop.complete

{
  "version":"1.0",
  "event":"stop.complete",
  "event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "uptime_id":"cczpplpv",
    "reference_id":"null"
}

 transcoder.stop.complete

{
  "version":"2.0",
  "event_type":"transcoder.stop.complete",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "uptime_id":"vbbywpbz",
    "reference_id":"null"
}

 Occurs when the transcoder has stopped and is no longer available.
audio.started

{
  "version":"1.0",
  "event":"audio.started",
  "event_id":"c0d3e142-ac5d-41b5-9453-d60ff14e5849",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "stream_name":"3920b4c6.stream",
    "codec": "AAC",
    "reference_id":"null"
}

 transcoder.audio.started

{
  "version":"2.0",
  "event_type":"transcoder.audio.started",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "stream_name":"3920b4c6.stream",
    "codec":"AAC",
    "reference_id":"null"
}

 Occurs when a running transcoder has started receiving audio.
audio.stopped

{
  "version":"1.0",
  "event":"audio.stopped",
  "event_id":"a5b3e832-ac5d-41b5-9453-d60ff14e9847",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "stream_name":"3920b4c6.stream",
    "reference_id":"null"
}

 transcoder.audio.stopped

{
  "version":"2.0",
  "event_type":"transcoder.audio.stopped",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "stream_name":"3920b4c6.stream",
    "height":"720",
    "width":"1280",
    "codec_string":"avcl.4d402a",
    "codec":"H264",
    "profile":"Main",
    "level":"1.2",
    "reference_id":"null"
}

 Occurs when a running transcoder has stopped receiving audio.
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"
}

 transcoder.video.started

{
  "version":"2.0",
  "event_type":"transcoder.video.started",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "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.
video.stopped

{
  "version":"1.0",
  "event":"video.stopped",
  "event_id":"n5e3e832-ac5d-41b5-9453-d60ff14e5013",
  "event_time":1621437110.6554534,
  "object_type":"transcoder",
  "object_id":"vxbfbxwv",
  "object_data":{
    "stream_name":"3920b4c6.stream",
    "reference_id":"null"
}

 transcoder.video.stopped

{
  "version":"2.0",
  "event_type":"transcoder.video.stopped",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "stream_name":"3920b4c6.stream",
    "reference_id":"null"
}

 Occurs when a running transcoder has stopped receiving video.
Info

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:

Copy
Copied
"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

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

{
  "version":"1.0",
  "event":"converting",
  "event_id":"acf71a9c-5716-4a91-8179-8a0e131fd8b0",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id":"b3hjs7ty",
    "transcoder_uptime_id":"blc5grjh"
}

 Not available Not available Occurs when a recording has been created and conversion to mp4 format begins.
uploading

{
  "version":"1.0",
  "event":"uploading",
  "event_id":"dcf81a9c-5716-4a91-8179-8a0e131fd8b2",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id":"b3hjs7ty",
    "transcoder_uptime_id":"blc5grjh"
}

 Not available Not available Occurs when a recording is being uploaded to account storage.
completed

{
  "version":"1.0",
  "event":"completed",
  "event_id":"e16c2606-c628-4fa5-ae76-e64b5be56573",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id":"b3hjs7ty",
    "transcoder_uptime_id":"blc5grjh",
    "file_name":"filename.mp4",
    "file_size":"117957690",
    "duration":"546550",
    "download_url":"https://url.mp4"
}

 Not available Not available Occurs when a recording is complete and available in account storage.
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",
}

 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:

  • 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
no_video

{
  "version":"1.0",
  "event":"no_video",
  "event_id":"dcx71a9c-5716-4a94-8179-8a0e231fd8b4",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id":"b3hjs7ty",
    "transcoder_uptime_id":"blc5grjh"
}

 Not available Not available Occurs when no video content is found for the recording.
deleted

{
  "version":"1.0",
  "event":"deleted",
  "event_id":"zpf71a9c-5716-4a91-8179-8a0e131fd8b1",
  "event_time":1621437110.6554534,
  "object_type":"recording",
  "object_id":"gVkjkJfS",
  "object_data":{
    "transcoder_id":"b3hjs7ty"
    "transcoder_uptime_id":"blc5grih",
}

 Not available Not available Occurs when a recording is deleted.

Note: uptime_id is deprecated. Use transcoder_uptime_id instead.

Real-time stream

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

{
  "version":"1.0",
  "event":"video.started",
  "event_id":"e0e3e832-ac5d-41b5-9453-d60ff14e5010",
  "event_time":1621437110.6554534,
  "object_type":"real_time_stream",
  "object_id":"vxbfbxwv",
  "object_data":{
    "name":"3920b4c6.stream",
    "reference_id":"null"
}

 real_time_stream.started

{
  "version":"2.0",
  "event_type":"real_time_stream.started",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":2024-10-15T08:03:43+0000,
  "object_id":"vxbfbxwv",
  "payload":{
    "name":"3920b4c6.stream",
    "reference_id":"null"
}

 Occurs when a real-time stream has started streaming.
video.stopped

{
  "version":"1.0",
  "event":"video.stopped",
  "event_id":"n5e3e832-ac5d-41b5-9453-d60ff14e5013",
  "event_time":1621437110.6554534,
  "object_type":"real_time_stream",
  "object_id":"vxbfbxwv",
  "object_data":{
    "name":"3920b4c6.stream",
    "reference_id":"null"
}

 real_time_stream.stopped

{
  "version":"2.0",
  "event_type":"real_time_stream.stopped",
  "event_id":"7ab488a5-1038-4bfc-9bee-c90bdef01689",
  "event_time":"2024-10-15T16:32:28Z",
  "object_id":"vxbfbxwv",
  "payload":{
    "name":"3920b4c6.stream",
    "reference_id":"null"
}

 Occurs when a real-time stream has stopped streaming.

More resources

© 2007-2024 Wowza Media Systems, ™ LLC. All rights reserved.   Security & Privacy Policy | Legal | System Status