Receive Wowza Video event notifications with webhooks

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

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. Instead, 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 documentation 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 transcoder stops.

{
  "version": 1.0,
  "event": "stop.complete",
  "event_id": "9be47e2a-b5ff-492a-a291-c7be79c060ba",
  "event_time": 1588864470.813283,
  "object_type": "transcoder",
  "object_id": "pl3fff7q",
  "object_data": {
    "uptime_id": 7cb5yfnx
  }
}

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
version	The version of the Wowza webhook envelope.
event	The event triggered by the object. See the Transcoder and live stream and Recording tables for a complete list of events.
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 Unix epoch 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 recordings, the object_id is the recording ID. You can use these IDs to locate the object that triggered the event in Wowza Video.
object_data	Data relevant to the object and event that triggered the webhook.

See the Transcoder and live stream and Recording tables for example payloads for each event triggered.

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.

1. Enable the webhook integration in Wowza Video.
   1. Log into Wowza Video, select your user name from the menu bar, and then select Account Settings.
   2. On the Integrations page, select Enable for the webhook integration.
   3. Enter the URL you want event notifications sent to.
      Ultimately, this will be the URL for the webhook endpoint you build in step 2. For testing webhook payloads prior to building your endpoint, you can use a generally available webook listener, like http://webhook.site.
   4. (Optional) Select Use basic authentication if your webhook endpoint requires authentication for POST requests, and then enter the username and password required by your endpoint.
2. 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. You'll need to make sure 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 enable Use basic authentication, make sure your endpoint authenticates POST requests. When the setting is enabled, Wowza Video sends basic authentication credentials in the Authorization header. 

As you're creating 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], POST /live_streams, and PATCH /live_streams/[ID] for more information.
  Example request

  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. Wowza Video reattempts notifications if you update the webhook endpoint URL or after 5 minutes pass.
• Wowza Video maintains an open connection to the webhook endpoint for 5 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 documentation