The Wowza Streaming Engine™ Webhooks.json configuration file located at [install-dir]/conf/Webhooks.json is used to define how webhook events are generated and delivered. It specifies the source identity, filtering criteria, and delivery endpoints for your webhooks.
Note: The Webhooks.json file was introduced with Wowza Streaming Engine 4.9.6. This reference applies to the file as installed with the latest version of Wowza Streaming Engine.
Webhooks.json file reference
The top-level webhooks object in the Webhooks.json configuration file serves as the primary container object, defining all aspects of the webhook configuration. Each JSON file is organized into the following fields:
- debugLog (boolean): Optional. If true, logs a warning, for example, when a request to a target endpoint fails or returns a non-200 status code.
- source (string): Optional. Identifies the origin of events that trigger the webhook, in this case, the Wowza Streaming Engine instance. This setting is helpful when multiple servers run in parallel, each with its own Webhooks.json configuration file. If omitted, the Wowza Streaming Engine GUID from the [install-dir]/conf/Server.guid file is used.
- filters (array): Required. Defines which events should trigger the webhook—for example, stream start or stream stop.
- id (string): Required. Identifies the filter and is used in REST API operations. Must be a unique value.
- enabled (boolean): Required. Enables the filter if set to true. If set to false, the event is not emitted based on the criteria.
- criteria (string): Required. Specifies the criteria that determine if the event passes or not. Required to trigger an event based on the criteria. For more, see Filter criteria details and Filter criteria examples.
- targetRef (string): Required. Assigns the target reference for the delivery endpoint that receives the webhook payloads when events occur.
- targets (array): Required. Specifies a list of delivery endpoints that receive the webhook payloads when events occur. Each target object contains details such as the target URL, custom headers, and authentication method (for example, JWT).
- id (string): Required. Maps each target object to an object in the filters array based on the targetRef key. Must be a unique value.
- url (string): Required. Identifies the webhook endpoint URL used to receive the webhook payload when events occur.
- headers (array): Optional. Defines a list of custom HTTP headers that are included in every webhook request sent to the target URL. When sending webhook notifications, authorization and custom headers tell the receiving server that the webhook sender is trusted. For additional information, refer to the JSON Web Token (JWT) details.
- name (string): Optional. Serves as the header name.
- value (string): Optional. Serves as the header value.
- auth (object): Optional. Adds cryptographic authentication in the form of JSON Web Token (JWT) and defines how the webhook request should be authenticated. For additional information, refer to the JSON Web Token (JWT) details.
- type (string): Optional. Tells the system to generate a JWT for authentication. Possible value is jwt.
- secret (string): Optional. Indicates the shared secret used to sign the JWT so the receiving endpoint can verify it.
Filter criteria details
Each filters array in the Webhooks.json file contains a criteria property that determines which events are matched and forwarded to the target endpoint. The criteria property uses a path expression that describes the event context. The general structure of this path is:
vHost.{vHostName}.app.{appName}.appInstance.{instanceName}.stream.{streamName}[.options.{optionName}].state.{state}
Where each entity can be described as follows:
- vHost: Identifies the virtual host (VHost) where the event occurred.
- app: Identifies the application name that triggered the event.
- appInstance: Identifies the application instance where the event occurred.
- stream: Identifies the stream that triggered the event.
- options: Serves as an additional and optional qualifier, for example, when targeting recording or rec-segment events.
- state: Identifies the state of the event for various entities in the object hierarchy.
An example event context looks similar to:
"context": {
"vHost": "myVHost",
"app": "myApp",
"appInstance": "myAppInstance",
"stream": "myStream",
"options": "recording",
"state": "failed"
}
Wildcards and terminators
Criteria filters use expressions with wildcards (*) and terminators (>) to determine which events are captured. Wildcards (*) match any value for a specific entity in the object hierarchy. The terminator (>) symbol in a criteria expression instructs the filter to stop evaluating subsequent context levels. If all components to the left of the terminator (>) match, the event is considered a match, and the filter passes regardless of what comes after.
Filter criteria examples
The following table provides examples of filter criteria expressions that can be used to capture different events. To better understand the webhook notifications that Wowza Streaming Engine supports, see the Supported webhook events section.
| Filter criteria expression | Description |
| > | Delivers supported webhook events to the configured target from all virtual hosts on the server. |
| vHost.myVhost.> | Delivers supported webhook events to the configured target from the specific myVhost virtual host. |
| vHost.*.app.*.> | Delivers supported webhook events to the configured target from all applications and virtual hosts. |
| vHost.*.app.myApp.> | Delivers supported webhook events to the configured target from the myApp application, across any virtual host. |
| vHost.*.app.*.appInstance.*.> | Delivers supported webhook events to the configured target from any application instance, application, or virtual host. |
| vHost.*.app.*.appInstance.myInstance.> | Delivers supported webhook events to the configured target only from the myInstance application instance, regardless of application or virtual host. |
| vHost.*.app.*.appInstance.*.stream.*.> | Delivers supported webhook events to the configured target from all streams on the server. |
| vHost.*.app.*.appInstance.*.stream.myStream.> | Delivers supported webhook events to the configured target only from the myStream stream, regardless of application instance, application, or virtual host. |
| vHost.*.app.myApp.appInstance.*.stream.*.state.* | Delivers supported webhook events to the configured target when any stream for the myApp application changes state, regardless of the virtual host. |
| vHost.*.app.myApp.appInstance.*.stream.myStream.state.started | Delivers supported webhook events to the configured target when the myStream stream in the myApp application starts, regardless of the virtual host. |
| vHost.*.app.myApp.appInstance.*.stream.myStream.options.recording.> | Delivers supported webhook events to the configured target when any recording event occurs for the myStream stream in the myApp application, regardless of the application instance or virtual host.
Note: This filter doesn't capture recording segment events. |
| vHost.*.app.myApp.appInstance.*.stream.myStream.options.rec-segment.state.started | Delivers supported webhook events to the configured target when any recording segment has started for the myStream stream in the myApp application, regardless of the application instance or virtual host. |
JSON Web Token (JWT) details
Wowza Streaming Engine can be configured to include a JSON Web Token (JWT) with each webhook request. This mechanism enables the receiving endpoint to verify the authenticity of incoming Wowza Streaming Engine notifications while preventing unauthorized systems from sending spoofed events.
How it works:
- A standard JWT is constructed with a header, payload, and signature.
- The payload includes a single sub (subject) claim, which is set to the event name (for example, stream.started).
- The token is signed using the HMAC with SHA-256 (HS256) algorithm and the configured shared secret.
- The resulting JWT is sent in the request as an HTTP header:
Authorization: Bearer <token>
- Both Wowza Streaming Engine and your receiving endpoint must be configured with the same shared secret.
- Before processing the request, the receiver validates the JWT by verifying the signature (HS256) and ensuring the sub claim matches the event.
Note: You can use this JSON Web Token (JWT) Debugger to decode, validate, and verify your JWTs. Paste the JWT and enter the secret used to sign the JWT to verify the signature. The JWT is the bearer token that's included in the Authorization header of your HTTP webhook request.
