Wowza Streaming Cloud webhook event reference documentation

Originally Published on 12/11/2020 | Updated on 05/28/2021 7:54 am PDT

Use webhooks to listen for and respond to events in your Wowza Streaming Cloud 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 Streaming Cloud 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 Streaming Cloud.
object_data Data relevant to the object and event that triggered the webhook.

Transcoder and live stream

Wowza Streaming Cloud 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 (beta) of the Wowza Streaming Cloud 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 Streaming Cloud 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":{
    "uptime_id": "blc5grih",
    "transcoder_id": "b3hjs7ty"
}

 Occurs when a recording is deleted.
 

More resources

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

Thank you for providing feedback to help us improve our documentation!

If you need immediate help for an urgent issue, open a support ticket to get help from one of our technical support engineers. (You must have a valid Maintenance and Support contract to get technical support.)

© 2007–2021 Wowza Media Systems, LLC. All rights reserved.   Terms Privacy Trademarks Legal