Mux sends webhook events to the addresses that you configure for an environment. You can configure these addresses in the Mux Dashboard, or you can use the Webhooks APIAPI. Use the API when you automate your environment setup, for example in provisioning scripts or infrastructure-as-code workflows.

Webhooks are scoped to one environment. Each request to the Webhooks API operates on the webhooks in the environment of your access token.

Create a webhook

Send a POST request to create a webhookAPI. Set address to the URL where Mux must send event notifications. The address must be unique among the webhooks in the environment.

curl https://api.mux.com/system/v1/webhooks \
  -H "Content-Type: application/json" \
  -X POST \
  -d '{ "address": "https://example.com/webhook" }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

The response includes the new webhook and its signing_secret. New webhooks are enabled immediately.

{
  "data": {
    "id": "abc12d",
    "address": "https://example.com/webhook",
    "enabled": true,
    "created_at": "2026-07-15T12:00:00.000000Z",
    "signing_secret": "9d0hnvbtpk3rfqe0m8s2a71cu5j6l4gd"
  }
}

If a webhook with the same address already exists in the environment, the request fails with a 400 response.

List and retrieve webhooks

Send a GET request to list the webhooksAPI in the environment. The response is sorted by creation time, with the most recent webhook first.

curl https://api.mux.com/system/v1/webhooks \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

{
  "data": [
    {
      "id": "fjk04c",
      "address": "https://example.com/webhook2",
      "enabled": false,
      "created_at": "2026-07-21T17:05:32.000000Z"
    },
    {
      "id": "abc12d",
      "address": "https://example.com/webhook",
      "enabled": true,
      "created_at": "2026-07-15T12:00:00.000000Z"
    }
  ],
  "total_row_count": 2,
  "page": 1,
  "limit": 25
}

The list endpoint supports the page and limit pagination parameters. The total_row_count value is the total number of webhooks in the environment, not the number of items on the page.

To get one webhook by its ID, send a GET request to retrieve a webhookAPI.

curl https://api.mux.com/system/v1/webhooks/${WEBHOOK_ID} \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

List and retrieve responses do not include the signing_secret. Mux returns the secret one time only, in the create response.

Update a webhook

Send a PATCH request to update a webhookAPI. You can change the address, the enabled status, or both. Include at least one of the two fields. Fields that you omit do not change. A new address must be unique among the webhooks in the environment.

curl https://api.mux.com/system/v1/webhooks/${WEBHOOK_ID} \
  -H "Content-Type: application/json" \
  -X PATCH \
  -d '{ "address": "https://example.com/new-webhook", "enabled": false }' \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

Set enabled to false to stop event notifications to the webhook without deletion. The webhook keeps its ID and signing secret. Set enabled to true to start event notifications again.

Delete a webhook

Send a DELETE request to delete a webhookAPI.

curl https://api.mux.com/system/v1/webhooks/${WEBHOOK_ID} \
  -X DELETE \
  -u ${MUX_TOKEN_ID}:${MUX_TOKEN_SECRET}

A successful request returns a 204 response with no body. Mux stops all event notifications to the address, and the webhook no longer appears in list or retrieve responses.

After deletion, the address is available again for a new webhook. The new webhook gets a new ID and a new signing secret. Update your signature verification code with the new secret.

Error responses

Error responses from the Webhooks API contain an error object with a type and an array of messages.

{
  "error": {
    "type": "invalid_parameters",
    "messages": ["A webhook with this address already exists"]
  }
}