# Manage webhooks with the API

Use the Webhooks API to create, list, update, and delete the webhooks for an environment. Use this guide when you configure webhooks from code instead of the Mux Dashboard.

Mux sends [webhook events](/docs/core/listen-for-webhooks) to the addresses that you configure for an environment. You can configure these addresses in the [Mux Dashboard](https://dashboard.mux.com/settings/webhooks), or you can use the <ApiRefLink href="/docs/api-reference/system/webhooks">Webhooks API</ApiRefLink>. 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.

<Callout type="info" title="Access token permissions">
  The Webhooks API requires an access token with **System** permissions. Read operations require `system:read`. Create, update, and delete operations require `system:write`. See [Make API requests](/docs/core/make-api-requests) for more about access tokens.
</Callout>

## Create a webhook

Send a POST request to <ApiRefLink href="/docs/api-reference/system/webhooks/create-webhook">create a webhook</ApiRefLink>. Set `address` to the URL where Mux must send event notifications. The address must be unique among the webhooks in the environment.

```bash
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.

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

<Callout type="warning" title="Store the signing secret now">
  The `signing_secret` is only included in the create response. You cannot retrieve it again from the API. Store it in a secure location, then use it to [verify webhook signatures](/docs/core/verify-webhook-signatures).
</Callout>

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 <ApiRefLink href="/docs/api-reference/system/webhooks/list-webhooks">list the webhooks</ApiRefLink> in the environment. The response is sorted by creation time, with the most recent webhook first.

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

```json
{
  "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](/docs/core/make-api-requests#api-pagination). 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 <ApiRefLink href="/docs/api-reference/system/webhooks/get-webhook">retrieve a webhook</ApiRefLink>.

```bash
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 <ApiRefLink href="/docs/api-reference/system/webhooks/update-webhook">update a webhook</ApiRefLink>. 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.

```bash
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 <ApiRefLink href="/docs/api-reference/system/webhooks/delete-webhook">delete a webhook</ApiRefLink>.

```bash
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`.

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

| Status | Cause |
| :--- | :--- |
| `400` | The request is not valid. For example, the address is already in use, the pagination parameters are not valid, or an update request contains no fields. |
| `404` | No webhook with the given ID exists in the environment. |