Create webhooks to monitor streaming events in Wowza Streaming Engine

Updated on 10/08/2025 8:31 am PDT

Wowza Streaming Engine 4.9.6 adds webhook functionality to provide real-time notifications for key live and video-on-demand (VOD) streaming events. Instead of continuously polling the REST API, you can now register webhook endpoints to receive event updates automatically as they happen. These enhancements improve both efficiency and responsiveness, making it easier to monitor, automate, and manage streaming workflows with minimal overhead.

This article explains how to set up the WebhookListener module in Wowza Streaming Engine using XML and JSON configurations, as well as a text editor. If you prefer a more programmatic approach to managing your webhook notifications, see Create webhooks to monitor streaming events using the Wowza Streaming Engine REST API.

Overview

The webhooks feature in Wowza Streaming Engine requires a one-time configuration of Server.xml and Webhooks.json.

When you update the Server.xml file, you ensure that the WebhookListener module is loaded when Wowza Streaming Engine starts. The Webhooks.json file defines how webhook events are generated and delivered. This file specifies the source identity, filtering criteria, and delivery endpoints for your webhooks.

To better understand the events you can capture, see Supported webhook events.

Before you start

Before starting with the steps in this guide, consider the following:

Supported webhook events

Wowza Streaming Engine supports notifications for the following webhook events. For specific examples of how to use these events, refer to the Filter criteria details.

Application webhook events

Context: Applies to application-level events for live and VOD streams.

Event name Description
app.shutdown Sent when an application shuts down on the Wowza Streaming Engine server.
app.started Sent when the first stream for an application starts on the Wowza Streaming Engine server. For VOD content, this event is triggered only the first time the application starts, and not on subsequent restarts.

Sample application started event

{
  "timestamp": 1758657755708,
  "name": "app.started",
  "context": {
    "state": "started",
    "appInstance": "_definst_",
    "vhost": "_defaultVHost_",
    "app": "live"
  },
  "id": "73afbe7d-f1c4-4b90-ba06-8ef0d9a0ab76",
  "source": "myWSEInstanceName",
  "version": "1.0"
}

Live stream webhook events

Context: Applies when ingesting and publishing live streams to Wowza Streaming Engine using any compatible encoding inputs.

Event name Description
stream.started Sent each time a live stream is ingested and when it becomes available as an incoming stream.
stream.stopped Sent each time a live stream stops and when it's no longer available as an incoming stream.

Sample live stream started

{
  "timestamp": 1758657755812,
  "name": "stream.started",
  "context": {
    "state": "started",
    "stream": "myStream",
    "appInstance": "_definst_",
    "vhost": "_defaultVHost_",
    "app": "live"
  },
  "id": "6e1f1e63-411c-4155-bb4f-322e90ee3f99",
  "source": "myWSEInstanceName",
  "version": "1.0"
}

Recording webhook events

Context: Applies when recording live streams via the Incoming Streams feature when using Wowza Streaming Engine Manager or the Wowza Streaming Engine REST API. For more information about this workflow, see:

Event name Description
recording.failed Sent when a live stream recording using the Incoming Streams feature fails due to one of these conditions:
  • Permissions errors related to the directory used to save the recording. For example, if the path is read-only, the recording can't be written to disk.
  • The disk is full and the recording can't be saved.
  • The file system path used for saving the recording is invalid.
recording.started Sent each time a live stream recording using the Incoming Streams feature in Wowza Streaming Engine Manager starts.
recording.stopped Sent each time a live stream recording using the Incoming Streams feature in Wowza Streaming Engine Manager stops.
recording.segment.ended Sent when a recording segment for a live stream recording using the Incoming Streams feature ends.
recording.segment.started Sent when a recording segment for a live stream recording using the Incoming Streams feature starts.

Sample recording failure event

{
  "data": {
    "error": "/usr/local/WowzaStreamingEngine/content/foo/myStream.mp4 (No such file or directory)"
  },
  "timestamp": 1758657777801,
  "name": "recording.failed",
  "context": {
    "state": "error",
    "stream": "myStream",
    "appInstance": "_definst_",
    "vhost": "_defaultVHost_",
    "app": "live"
  },
  "id": "a22817db-12da-444f-8b5f-45e1235d5282",
  "source": "myWSEInstanceName",
  "version": "1.0"
}

Sample recording started event

{
  "id": "3e98d7e9-527a-4886-8185-1b62752240bf",
  "timestamp": 1758730312514,
  "name": "recording.started",
  "source": "myWSEInstanceName",
  "version": "1.0",
  "context": {
    "app": "live",
    "appInstance": "_definst_",
    "stream": "myStream",
    "state": "started",
    "vhost": "_defaultVHost_"
  },
  "data": {
    "outputFile": "/home/user/repos/wowza/wse/install/content/myStream.mp4",
    "recorderMode": "version"
  }
}

Re-streaming webhook events

Context: Applies when re-streaming live streams with MediaCaster and .stream files. For more, see About re-streaming with MediaCaster in Wowza Streaming Engine.

Note: With Wowza Streaming Engine 4.9.6, you can't use the following connection events directly in the criteria filters. In order to track connection events for your MediaCaster streams, you must use a more generic stream filter such as:

vHost.*.app.myApp.appInstance.*.stream.myStream.>
Event name Description
connection.failure Sent when a MediaCaster source connection using a .stream file has failed.
connection.started Sent when a .stream file begins attempting to open the socket connection with the remote endpoint.
connection.success Sent when a MediaCaster source connection using a .stream file has been successfully established.
stream.started Sent when a MediaCaster source is connected and the stream begins.
stream.stopped Sent when a stream ends, either due to timeout, failure, or shutdown of the MediaCaster.

Sample re-streaming success event

{
  "timestamp": 1758657755812,
  "name": "connect.success",
  "context": {
    "state": "success",
    "stream": "myStream",
    "appInstance": "_definst_",
    "vhost": "_defaultVHost_",
    "app": "live"
  },
  "id": "6e1f1e63-411c-4155-bb4f-322e90ee3f99",
  "source": "myWSEInstanceName",
  "version": "1.0"
}

1. Configure your Server.xml file

First, you must update your Server.xml configuration file. This ensures that the WebhookListener module is loaded when Wowza Streaming Engine starts. For more, see the Wowza Streaming Engine Server.xml configuration reference.

  1. In your text editor, open the Server.xml configuration file located at [install-dir]/conf/Server.xml.
  2. In the Server.xml, inside the ServerListeners element, add the following child element and <BaseClass>:
<ServerListener>
    <BaseClass>com.wowza.wms.webhooks.WebhookListener</BaseClass>
</ServerListener>
  1. Save your Server.xml file.
  2. Restart Wowza Streaming Engine.

2. Configure your Webhooks.json file

Next, define the rules and targets in the Webhooks.json file. This JSON configuration file defines how webhook events are generated and delivered. For more, see the Wowza Streaming Engine Webhooks.json configuration reference.

Note: In this section, we use Webhook.site to generate a unique URL endpoint to use as a test webhook destination. For more details, see Test your webhook notification.
  1. Go to Webhook.site and create a unique URL for your endpoint.
  2. In your text editor, open the Webhooks.json configuration file located at [install-dir]/conf/Webhooks.json.
  3. This file initially has everything disabled, but it provides a template for guidance. The basic structure looks similar to:
{
  "webhooks": {
    "source": "myWSEInstanceName",
    "filters": [
      {
        "id": "myAppStreamFilter",
        "enabled": false,
        "criteria": "vHost.*.app.myApp.appInstance.*.stream.*.state.*",
        "targetRef": "myEndpointName"
      },
      {
        "id": "myServerFilter",
        "enabled": false,
        "criteria": "vHost.myVhost.>",
        "targetRef": "myEndpointName2"
      },
      {
        "id": "myAppInstanceFilter",
        "enabled": false,
        "criteria": "vHost.myVhost2.app.*.appInstance._definst_.>",
        "targetRef": "myEndpointName"
      }
    ],
    "targets": [
      {
        "id": "myEndpointName",
        "url": "https://my.site.com/",
        "headers": [
          { "name": "Authorization", "value": "Bearer abc123token" },
          { "name": "X-Custom-Header", "value": "my-value" }
        ],
        "auth": {
          "type": "jwt",
          "secret": "abc123secret"
        }
      },
      {
        "id": "myEndpointName2",
        "url": "https://my.site2.com/",
        "headers": [
          { "name": "Authorization", "value": "Bearer def456token" },
          { "name": "X-Custom-Header", "value": "my-value2" }
        ],
        "auth": {
          "type": "jwt",
          "secret": "def456secret"
        }
      }
    ]
  }
}
  1. Add the following setup to your Webhooks.json. The endpoint url in the targets array is a placeholder. Replace it with your own value, or in this case, add the unique URL from the Webhook.site in step 1:
{
  "webhooks": {
    "source": "myWSEInstanceName",
    "filters": [
      {
        "id": "myServerFilter",
        "enabled": true,
        "criteria": "vHost._defaultVHost_.>",
        "targetRef": "myEndpointName"
      }
    ],
    "targets": [
      {
        "id": "myEndpointName",
        "url": "https://webhook.site/123e4567-e89b-12d3-a456-426614174000",
        "headers": [
          { "name": "Authorization", "value": "Bearer def456token" },
          { "name": "X-Custom-Header", "value": "my-value2" }
        ],
        "auth": {
          "type": "jwt",
          "secret": "def456secret"
        }
      }
    ]
  }
}
Note: In this example, we want to capture supported webhook events only from the _defaultVHost_ virtual host (VHost) and send them to the target endpoint. For information about authenticating the request, see JSON Web Token (JWT) details.
  1. After making configuration changes to the Server.xml or Webhooks.json file, restart Wowza Streaming Engine.

3. Test your webhook notification

In this section, we use Webhook.site to capture and inspect webhook notifications from Wowza Streaming Engine during development. This makes it easy to view raw payloads, confirm request formatting, and debug your setup.

Note: For production environments, you'll want to integrate webhooks in a more secure and scalable manner, for example, by using direct server endpoints to receive and process events in your app, event streaming processors such as Kafka, serverless functions like AWS Lambda, or no-code platforms like Zapier.
  1. Start a stream and send it to your Wowza Streaming Engine server. For more about publishing live streams, see Connect a live source to Wowza Streaming Engine.
  2. Click Incoming Streams in the contents panel for your live application. Your stream is listed as Active.
  3. Use the unique URL you created in the Webhook.site online tool to verify that webhook notifications from Wowza Streaming Engine are received. For example, you get a notification each time a stream starts or stops, or an application shuts down. A request payload looks similar to the Raw Content in the following screenshot:

More resources

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

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

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