Configure Webhooks for Wowza Video Intelligence

Video Intelligence webhook events are available starting with wowza-streaming-engine:latest-vif 4.11.1.1 with the Video Intelligence module enabled.

Note: Webhooks are dispatched by VIC (inside WSE), not by VIS. VIC receives detection JSON from VIS and forwards it to configured webhook endpoints. This means webhook delivery works even if VIS is on a different network and VIC handles the outbound HTTP calls.

Configure webhooks for Wowza Video Intelligence (VIF)

This guide explains how to configure Wowza Streaming Engine (WSE) to send real-time alerts when the Video Intelligence Framework (VIF) detects objects.

The configuration requires three steps:

1. Server.xml – Enable the WSE Webhook module.
2. Webhooks.json – Define where to send the webhook data.
3. video-intelligence.json – Define what triggers the webhook events.

Supported Video Intelligence webhook events

Event Name	Description
viDetection.entity.objects	Triggered when objects are detected in the video stream along with confidence scores.

Sample Video Intelligence event

{
  "id": "3e98d7e9-527a-4886-8185-1b62752240bf",
  "timestamp": 1758730312514,
  "name": "videoIntelligence.objects",
  "source": "myWSEInstanceName",
  "version": "1.0",
  "context": {
    "app": "live",
    "appInstance": "_definst_",
    "stream": "myStream",
    "videoIntelligence": "objects",
    "vhost": "_defaultVHost_"
  },
  "data": {
    "cat": "100%",
    "dog": "100%"
  }
}

Configuration Method 1 – Using XML and JSON Files

Step 1: Configure Server.xml

1. Open the file located at [install-dir]/conf/Server.xml.
2. Add the WebhookListener module as the first entry inside the <ServerListeners> element.
3. Save the file.

<ServerListener>
  <BaseClass>com.wowza.wms.webhooks.WebhookListener</BaseClass>
</ServerListener>

Step 2: Configure Webhooks.json for VIF Events

1. Open the file located at [install-dir]/conf/Webhooks.json.
2. Create webhook filters to capture VIF events.

Example: Capture all Video Intelligence events

{
  "webhooks": {
    "source": "myWSEInstanceName",
    "filters": [
      {
        "id": "vifAllEventsFilter",
        "enabled": true,
        "criteria": "vHost.*.app.*.appInstance.*.stream.*.options.viDetection.entity.*",
        "targetRef": "myVIFEndpoint"
      }
    ],
    "targets": [
      {
        "id": "myVIFEndpoint",
        "url": "https://your-webhook-endpoint.com/vif-events",
        "headers": [
          {
            "name": "Authorization",
            "value": "Bearer your-token-here"
          }
        ],
        "auth": {
          "type": "jwt",
          "secret": "your-jwt-secret"
        }
      }
    ]
  }
}

Example: Capture object detection events for a specific stream

{
  "webhooks": {
    "source": "myWSEInstanceName",
    "filters": [
      {
        "id": "vifObjectsFilter",
        "enabled": true,
        "criteria": "vHost.*.app.live.appInstance.*.stream.myStream.options.viDetection.entity.objects",
        "targetRef": "myVIFEndpoint"
      }
    ],
    "targets": [
      {
        "id": "myVIFEndpoint",
        "url": "https://your-webhook-endpoint.com/object-detection",
        "headers": [
          {
            "name": "Content-Type",
            "value": "application/json"
          }
        ]
      }
    ]
  }
}

Step 3: Restart Wowza Streaming Engine

After updating configuration files, restart the server so the changes take effect.

Configuration Method 2 – Using the REST API

Step 1: Configure Server.xml via REST API

curl -X PUT --basic -u "USERNAME:PASSWORD" \
-H "Accept:application/json; charset=utf-8" \
-H "Content-Type:application/json; charset=utf-8" \
"http://localhost:8087/v2/servers/_defaultServer_" \
-d '{
  "serverListeners": {
    "serverName": "_defaultServer_",
    "serverListeners": [
      {
        "order": 0,
        "baseClass": "com.wowza.wms.webhooks.WebhookListener"
      }
    ]
  }
}'

Step 2: Configure Webhook filters

Create a filter for all VIF events

curl -X POST --basic -u "USERNAME:PASSWORD" \
-H "Accept: application/json; charset=utf-8" \
-H "Content-Type: application/json; charset=utf-8" \
"http://localhost:8087/v2/servers/_defaultServer_/webhooks/filters" \
-d '{
  "id": "vifAllEventsFilter",
  "enabled": true,
  "criteria": "vHost.*.app.*.appInstance.*.stream.*.options.viDetection.entity.*",
  "targetRef": "myVIFEndpoint"
}'

Create the webhook endpoint

curl -X POST --basic -u "USERNAME:PASSWORD" \
-H "Accept: application/json; charset=utf-8" \
-H "Content-Type: application/json; charset=utf-8" \
"http://localhost:8087/v2/servers/_defaultServer_/webhooks/targets" \
-d '{
  "id": "myVIFEndpoint",
  "url": "https://your-webhook-endpoint.com/vif-events",
  "headers": [
    {
      "name": "Authorization",
      "value": "Bearer your-token-here"
    }
  ]
}'

Enable VIF event generation (video-intelligence.json)

By default, VIF processes video but does not emit webhook events. You must explicitly enable this behavior in the VIF configuration file.

1. Open video-intelligence.json in your conf/ directory.
2. Locate the streams array.
3. Find the appropriate stream configuration.
4. Update the Webhooks event method.

{
  "active": true,
  "app_name": "live",
  "stream_name": "object.*",
  "vif_event_listeners": {
    "Webhooks": {
      "class_name": "WebhookEvent2",
      "method": "immediate"
    },
    "Overlays": {
      "class_name": "OverlayEvent",
      "method": "immediate",
      "properties": {
        "show_stats": true
      }
    }
  }
}

Webhook configuration options

Method	Description	Best For
disabled	No webhook events are sent.	Inactive streams.
immediate	Sends an event immediately when detection occurs.	Real-time alerts.
batch	Groups detections before sending.	High-traffic streams.
rollup	Aggregates statistics over time instead of individual detections.	Analytics and dashboards.

Global vs stream-specific settings

• Root level: Sets defaults for all VIF-enabled streams.
• Streams level: Overrides defaults for specific streams matching the stream_name regex.

Restart the server

curl -X PUT --basic -u "USERNAME:PASSWORD" \
-H "Accept:application/json; charset=utf-8" \
-H "Content-Type:application/json; charset=utf-8" \
"http://localhost:8087/v2/servers/_defaultServer_/actions/restart"

Filter criteria patterns for VIF

Filter Criteria	Description
vHost.*.app.*.appInstance.*.stream.*.options.viDetection.entity.*	All VIF events from all streams.
vHost.*.app.live.appInstance.*.stream.*.options.viDetection.entity.*	All VIF events from the live application.
vHost.*.app.*.appInstance.*.stream.myStream.options.viDetection.entity.objects	Object detection events only for myStream.

Testing your webhook configuration

1. Go to Webhook.site and copy your unique testing URL.
2. Update the Webhooks.json target URL.
3. Restart Wowza Streaming Engine.
4. Start a VIF-enabled stream.
5. Monitor Webhook.site for incoming events.
6. Verify the JSON payload structure.

Security best practices

Use JWT Authentication

{
  "auth": {
    "type": "jwt",
    "secret": "your-shared-secret-key"
  }
}

The JWT token will be sent in the Authorization header:

Authorization: Bearer <jwt-token>

Validate webhook signatures

1. Extract the JWT token from the Authorization header.
2. Verify the signature using your shared secret.
3. Confirm the sub claim matches the event name.
4. Process only validated requests.

Troubleshooting

VIF Events not being sent

1. Verify the WebhookListener is loaded by checking Wowza logs.
2. Confirm the filter criteria match the event context.
3. Ensure "enabled": true in the filter configuration.
4. Verify the Video Intelligence module is running.

Enable debug logging

{
  "webhooks": {
    "debugLog": true,
    "source": "myWSEInstanceName"
  }
}

Check the Wowza logs located at [install-dir]/logs/ for webhook-related messages.