Wowza Video webhook event reference documentation

Updated on 05/30/2023 11:20 am PDT

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

Note: 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.

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.

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

Note: These events are triggered for transcoder actions in both the live stream and transcoder workflows.
Event Sample payload 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"
 }

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

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

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

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

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

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

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

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

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

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

 Occurs when a running transcoder has stopped receiving video.

Note: 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.

Recording

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

Event Sample payload 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"
}

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

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

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

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

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

 Occurs when a recording is deleted.

Note: uptime_id is deprecated. Use transcoder_uptime_id instead.

More resources

Was this article helpful?
Thank you for your feedback!
User Icon

<p align="left">Thank you for providing feedback to help us improve our documentati

© 2007–2023 Wowza Media Systems™, LLC. All rights reserved.   Security & Privacy PolicyLegalSystem Status