Receive Wowza Video event notifications with webhooks

Use webhooks to respond to events that occur in your Wowza Video account.

Info

The webhooks feature is currently offered under limited availability, meaning the functionality is available to select Wowza Video users. If you need this functionality, please email us at customerservice@wowza.com.

Info

This topic only applies to version 2.0 of the REST API and the latest Wowza Video user interface.

About Webhooks

Webhooks are notifications that Wowza Video sends when specific events happen in your Wowza Video account. Instead of using the REST API to poll your account and determine when an event has occurred, like when a recording is uploaded and available, Wowza pushes notifications to you. Using webhooks can save resources since you don't have to dedicate code and bandwidth to sending repeated REST API requests; rather, you create a webhook endpoint that listens for the event notification and then your application can respond to the notification when it's received.

See Wowza Video webhook event reference to learn what events Wowza Video sends.

Sample webhook payload

Wowza Video sends webhook data in JSON format through a POST request. The following sample webhook payload is sent when a video is updated.

Copy

Copied

   {
    "event_type": "video.updated",
      "event_id": "9be47e2a-b5ff-492a-a291-c7be79c060ba",
      "event_time": "2024-10-15T16:32:28Z",
      "object_id": "d8e89dd5-6263-49ff-b98e-4a768ea21a39",
      "payload": {
         "id": "d8e89dd5-6263-49ff-b98e-4a768ea21a39",
         "name": "Test",
         "description": "Test webhooks",
         "duration_in_ms": 50348,
         "unpublish": false,
         "unpublished_at": "2024-10-15T08:03:43+0000",
         "published": true,
         "published_at": "2024-10-15T08:03:43+0000",
         "tags": [],
         "remote": false,
         "category_id": "b2575006-2b9a-4a1d-8bd2-f5a8d93e9e67",
         "no_ads": false,
         "ad_keywords": "",
         "created_at": "2024-10-15T08:03:43+0000",
         "updated_at": "2024-10-15T16:32:28+0000",
        "state": "FINISHED",
        "encoding_progress": 100,
        "upload_progress": 100,
        "error_message": "",
        "deactivated": false,
        "images": [
          {
            "type": "image_0",
             "url": "https://wv-cdn-00-00-staging.flowplayer.com/7ac9b5f3-3ce7-483f-a7cb-80524729517b/i/v-i-d8e89dd5-6263-49ff-b98e-4a768ea21a39-1728979446304.jpg"
          },
          {
            "type": "image_1",
            "url": "https://wv-cdn-00-00-staging.flowplayer.com/7ac9b5f3-3ce7-483f-a7cb-80524729517b/i/v-i-d8e89dd5-6263-49ff-b98e-4a768ea21a39-1728979446304.jpg"
          }, 
         ],
       "encodings": [
        {
          "audio_bitrate_in_kbps": 125,
          "audio_channel": 2,
          "audio_codec": "mp4a-40-2",
          "audio_sample_rate": 48000,
          "height": 720,
          "width": 1280,
          "video_file_url": "https://wv-cdn-00-00-staging.flowplayer.com/7ac9b5f3-3ce7-483f-a7cb-80524729517b/cmaf/d8e89dd5-6263-49ff-b98e-4a768ea21a39/playlist_1728979423022.m3u8",
          "video_container": "cmaf",
          "video_codec": "avc1",
          "total_bitrate_in_kbps": 859,
          "created_at": "2024-10-15T08:04:12+0000",
          "size_in_bytes": 66384367
        },
        {
          "audio_bitrate_in_kbps": 0,
          "audio_channel": 0,
          "audio_codec": "aac",
          "audio_sample_rate": 0,
          "height": 432,
          "width": 768,
          "video_file_url": "https://wv-cdn-00-00-staging.flowplayer.com/7ac9b5f3-3ce7-483f-a7cb-80524729517b/v-d8e89dd5-6263-49ff-b98e-4a768ea21a39_720p.mp4",
          "video_container": "mp4",
          "video_codec": "h264",
          "total_bitrate_in_kbps": 4666,
          "created_at": "2024-10-15T08:04:38+0000",
          "size_in_bytes": 23489391
        }
      ],
      "drm": null,
      "shallow_copy": false,
      "shallow_copy_source_id": null,
      "multiple_audio_tracks": false,
      "audio_only": false,
      "version": 1,
      "thumbnails": null,
      "animated_previews": [],
      "origin": {
        "id": "zdvhfqmx",
        "type": "live_stream",
        "uptime_id": "wpcrwhrs"
      },
      "ad_insertion_points": null 
      }
   }

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
`event_type`	The event triggered by the object. For example, when a video is updated, the event type received in the webhook `video.updated` when a webhook event is received.
`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 ISO-8601 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 videos, the `object_id` is the video ID. You can use these IDs to locate the object that triggered the event in Wowza Video.
`payload`	Data relevant to the object and event that triggered the webhook.

Set up a webhook notification system

To receive event notifications, you'll enable webhooks for your account and create a webhook endpoint to receive the notifications in the Wowza Video UI.

Enable webhooks in Wowza Video.
1. Log into Wowza Video, click your user profile in the upper left of any screen, then click  Webhooks  under  Organization . 
2. Click Secret key on the Webhooks page and set a unique key. This key is used to authenticate the payload of the webhook notifications sent from Wowza Video.
3. Click +New webhook in the upper right corner of the Webhooks list.
4. Enter a name in the Name field and under the When menu, select the events you need to receive notifications for.
5. Click +Add condition under If , if you would like to add further conditions to your event notifications.
6. Enter the URL you want event notifications sent to in the Then, Send a notification to the following URL field. This will be the URL for the webhook endpoint you build in step 2. To test webhook payloads before building your endpoint, you can use a publicly available webhook listener, such as http://webhook.site .
7. Click Save webhook .
8. Repeat steps 2 to 7 to add new webhooks as needed.
Create a webhook endpoint on your server. Because this endpoint is on your server and part of your application, you can write this in any programming language you want. Ensure the endpoint:
- Has an associated public URL that Wowza Video can send notifications to.
- Receives event notifications. Wowza Video sends webhook data in JSON format through a POST request.
- If you set a Secret key, ensure your endpoint authenticates POST requests. When the secret key is enabled, Wowza Video sends it as a sha-256 key in the authorization header in webhook data.

As you create the webhook endpoint, it might be helpful to know the following:

If you have an ID in your system or application you want to associate with transcoder events and have returned in the transcoder webhook payloads, use the Wowza Video REST API to set the  reference_id . See POST/transcoders , PATCH/transcoders/ID for more information.

Example request

Copy

Copied

    curl -X POST \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer ${WV_JWT}" \
    -d '{
       "transcoder": {
         "billing_mode": "pay_as_you_go",
         "broadcast_location": "us_west_california",
         "buffer_size": 4000,
         "delivery_method": "push",
         "low_latency": true,
         "name": "MyABRtranscoder",
         "protocol": "rtsp",
         "transcoder_type": "transcoded",
         "reference_id": "mySystemID_01"
       } 
    }' "${WV_HOST}/api/${WV_VERSION}/transcoders"

If three consecutive event errors are logged, Wowza Video stops sending event notifications.
Once an event is created, you cannot update the webhook endpoint URL.
Wowza Video maintains an open connection to the webhook endpoint for 10 seconds. If the endpoint can't receive the  POST request in that amount of time, because of bandwidth or other issues, Wowza Video ends the connection.

More resources

Wowza Video webhook event reference