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 asset 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). Note: Mux makes an effort to deliver each message successfully once, but in certain situations duplicate webhook messages may be sent even if your service responds with a 2xx response code. Please ensure that your webhook handling mechanism treats duplicated event delivery appropriately.

Webhooks vs. polling

Please use webhooks to track asset status rather than polling the Asset API. 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.

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 async task so you can respond to the event immediately.

For more details on the Webhook event object definition, see Webhook Event API documentation.

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

• video.asset.created
• video.asset.ready
• video.asset.errored
• video.asset.updated
• video.asset.deleted
• video.asset.live_stream_completed
• video.asset.static_renditions.ready
• video.asset.static_renditions.preparing
• video.asset.static_renditions.deleted
• video.asset.static_renditions.errored
• video.asset.master.ready
• video.asset.master.preparing
• video.asset.master.deleted
• video.asset.master.errored
• video.asset.track.created
• video.asset.track.ready
• video.asset.track.errored
• video.asset.track.deleted

Upload Events

• video.upload.asset_created
• video.upload.cancelled
• video.upload.created
• video.upload.errored

Live Stream Events

• video.live_stream.created
• video.live_stream.connected
• video.live_stream.recording
• video.live_stream.active
• video.live_stream.disconnected
• video.live_stream.idle
• video.live_stream.updated
• video.live_stream.deleted

Simulcast Target Events

• video.live_stream.simulcast_target.created
• video.live_stream.simulcast_target.idle
• video.live_stream.simulcast_target.starting
• video.live_stream.simulcast_target.broadcasting
• video.live_stream.simulcast_target.errored
• video.live_stream.simulcast_target.deleted