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.
Notes:
- 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.
- When updating Wowza Streaming Engine from an earlier version to 4.9.6, the template Webhooks.json file is not created automatically. This is intentional to make sure the update process doesn't modify existing configuration files and to preserve user settings. To add the file manually, copy and paste it in the [install-dir]/conf folder. You can find a sample template in the Configure your Webhooks.json file section.
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 properties:
- debugLog (boolean): Optional. Enables detailed logging for webhook activity in the wowzastreamingengine_access.log file, useful for troubleshooting and debugging. The default value is false, which maintains standard logging behavior. When set to true, the webhooks engine and Wowza Streaming Engine REST API generate verbose debug entries, including success messages and delivery details.
- 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.
- maxRetryAttempts (integer): Optional. Enables the retry mechanism for webhook notifications. The default value is 0, and the maximum number of attempts can be set to 10. When enabled, the system automatically retries failed webhook deliveries caused by transient errors or network interruptions. The mechanism tracks delivery attempts, schedules retries using a fixed delay, and re-enqueues messages until delivery succeeds or the maximum retry limit is reached. Retry attempts are detailed in the wowzastreamingengine_access.log file.
- retryDelay (long): Optional. Defines the interval between retry attempts with units depending on the retryDelayUnit setting. If the retryDelay and retryDelayUnits are not set, the default value is 1000 milliseconds (or 1second). The maximum interval time can be set to 600,000 milliseconds (or 10 minutes).
- retryDelayUnit (string): Optional. Determines the time unit for the retryDelay property. Possible values are ms (milliseconds), s (seconds), and m (minutes). If retryDelay is unset but retryDelayUnits is changed (for example, to seconds), the delay becomes 1000 seconds (or approximately 16.7 minutes). Since this exceeds the 10-minute limit, it defaults back to 1000 ms (or 1 second).
- targetRef (string): Required. Assigns the target reference for the delivery endpoint that receives the webhook payloads when events occur. If the targetRef doesn't match any id in the targets array, the filter is skipped.
- 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.
Application events path
The general structure of this path for application events 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"
}
Server-level log events path
The general structure of this path for server-level log events is:
logLevel.{state}
Where each entity can be described as follows:
- logLevel: Indicates the severity of the log message, for example, warning, error, or info. With Wowza Streaming Engine 4.9.7 and later, we only provide the ability to capture error messages.
An example event context looks similar to:
"context": {
"logLevel": "error"
}
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._defaultVHost_.> | Delivers supported webhook events to the configured target from the specific _defaultVHost_ virtual host. |
| vHost.*.app.*.> | Delivers supported webhook events to the configured target from all applications and virtual hosts. |
| vHost.*.app.live.> | 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._definst_.> | Delivers supported webhook events to the configured target only from the _definst_ 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.live.appInstance.*.stream.*.state.* | Delivers supported webhook events to the configured target when any stream for the live application changes state, regardless of the virtual host. |
| vHost.*.app.live.appInstance.*.stream.myStream.state.started | Delivers supported webhook events to the configured target when the myStream stream in the live application starts, regardless of the virtual host. |
| vHost.*.app.live.appInstance.*.stream.myStream.options.recording.> | Delivers supported webhook events to the configured target when any recording event occurs for the myStream stream in the live application, regardless of the application instance or virtual host.
Note: This filter doesn't capture recording segment events. |
| vHost.*.app.live.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 live application, regardless of the application instance or virtual host. |
| logLevel.error | Delivers supported webhook events to the configured target when any error-level event appears in Wowza Streaming Engine server logs, for example, in the wowzastreamingengine_access.log or wowzastreamingengine_error.log files. |
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.
