Listen for webhooks

Mux uses webhooks to let your application know when things happen asynchronously, outside of an API request cycle. For example, you may want to update something on your end when an assetAPI transitions its status from processing to ready, or when a live stream starts or ends. When these asynchronous events happen, we'll make a POST request to the address you give us and you can do whatever you need with it on your end.

After a webhook is configured for an environment, notifications will be sent for all events for that environment.

If Mux doesn't receive a 2xx response from your system, we will continue to try the message for the next 24 hours (with an increasing delay between attempts).

Webhooks vs. polling

Please use webhooks to track asset status rather than polling the Asset APIAPI. Webhooks are much more efficient for both you and Mux, and we rate limit GET requests to the /assets endpoint, which means polling the /assets API doesn't scale.

Handling webhooks locally

A common gotcha for anyone new to working with webhooks is figuring out how to receive them when working in a local environment.

If your application is running on a local URL such as https://localhost:3000 or https://localhost:8080, you'll need to create a secure tunnel to this port on your machine to expose it to the world.

One approach to accomplishing this is using a tool like ngrok to expose your local application to the internet.

As an example, if your application is running on https://localhost:3000, you can run ngrok http 3000 in your terminal to get a public URL to your local application

If you're using a free ngrok account, you'll receive an auto-generated URL that will look something like this:

https://025c-2603-6010-fd04-a497-8cc9-f31e-1e0d-1406.ngrok.io/

You can then append your application's webhook handler path to the end of that URL and use it as the webhook endpoint within the Mux dashboard. A complete example webhook endpoint provided by ngrok might look something like this:

https://025c-2603-6010-fd04-a497-8cc9-f31e-1e0d-1406.ngrok.io/api/webhooks/mux

There is more detail on Mux and ngrok's integration and what is possible with it in ngrok's documentation here.

Configuring endpoints

Webhook endpoints are configured in the Mux dashboard under "Settings."

Enter a URL from your application that Mux will call for event notifications.

Receiving events

Mux will submit a POST request to the configured URL, which your application can treat the same as any other route. Your event handler can do things like update the state of the specified asset in your database, or trigger other work.

Note that a single request attempt will timeout after 5 seconds, after which the attempt is considered failed and will be reattempted. If you expect this will be a problem in your workflow, consider doing the work in an asynchronous task so you can respond to the event immediately.

For more details on the Webhook event object definition, see the example response.

Example response

{
  "type": "video.asset.ready",
  "object": {
    "type": "asset",
    "id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002"
  },
  "id": "3a56ac3d-33da-4366-855b-f592d898409d",
  "environment": {
    "name": "Demo pages",
    "id": "j0863n"
  },
  "data": {
    "tracks": [
      {
        "type": "video",
        "max_width": 1280,
        "max_height": 544,
        "max_frame_rate": 23.976,
        "id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002",
        "duration": 153.361542
      },
      {
        "type": "audio",
        "max_channels": 2,
        "max_channel_layout": "stereo",
        "id": "FzB95vBizv02bYNqO5QVzNWRrVo5SnQju",
        "duration": 153.361497
      }
    ],
    "status": "ready",
    "max_stored_resolution": "SD",
    "max_stored_frame_rate": 23.976,
    "id": "0201p02fGKPE7MrbC269XRD7LpcHhrmbu0002",
    "duration": 153.361542,
    "created_at": "2018-02-15T01:04:45.000Z",
    "aspect_ratio": "40:17"
  },
  "created_at": "2018-02-15T01:04:45.000Z",
  "accessor_source": null,
  "accessor": null,
  "request_id": null
}

Types of Events

Asset Events

Upload Events

Live Stream Events

Simulcast Target Events

These simulcast target events are useful when creating a UI that shows your users the status of their configured 3rd party endpoints. These events are handy when you want to build a UI that shows the state of each simulcast target and keep track of the state changes as they happen.

Web Input Events Beta

These events describe the states of Web Inputs during their lifecycle.