> ## Documentation Index
> Fetch the complete documentation index at: https://mintfax.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Update or remove a webhook endpoint

> Change the URL, change the subscribed events, pause an endpoint temporarily, or delete it permanently. PUT for updates, DELETE for permanent removal, `is_active: false` for a pause you can undo.

Registration is one moment; the endpoint lives on afterwards. URLs move to new backends, subscribed events change with new features, and endpoints sometimes need to be paused without being torn down. `PUT /webhooks/{webhook}` covers the mutations, `DELETE` is one-way, and `is_active: false` is the pause switch for when you might want the endpoint back later.

## Change the delivery URL

You have moved your webhook handler to a new host, or you noticed a typo in the URL you registered. Send a PUT with only the field you want to change. The endpoint keeps everything else, including its signing secret and its subscribed event list.

```bash theme={null}
curl -X PUT https://api.mintfax.com/v1/webhooks/we_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://api.example.com/webhooks/mintfax"
  }'
```

The response is the updated `WebhookEndpointResource`. The signing secret is unchanged and does not appear in the response - it is only ever shown at creation or after `POST /webhooks/{webhook}/rotate-secret`. The next event mintfax fires for this endpoint arrives at the new URL with the same `whsec_` secret you were already using.

## Change the events an endpoint receives

You added a top-up flow and now need `balance.topup` deliveries, or your team is dropping `fax.sending` because the per-attempt volume is noisy. Send the full list of events you want the endpoint to receive.

```bash theme={null}
curl -X PUT https://api.mintfax.com/v1/webhooks/we_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "events": ["fax.delivered", "fax.failed", "balance.topup"]
  }'
```

Valid values are `fax.queued`, `fax.sending`, `fax.delivered`, `fax.failed`, `balance.low`, and `balance.topup`. Maximum six items. Omitting `events` from the PUT body leaves the subscription list alone. Sending `"events": null` subscribes the endpoint to every event, current and future - the same semantics as at registration.

## Pause an endpoint without deleting it

You are debugging your handler, or the team that owns the endpoint is out for the week. You want deliveries to stop without losing the endpoint's id, secret, or subscription list. Flip `is_active` to `false`; every other field is preserved. Flip it back to `true` when you are ready to resume.

```bash theme={null}
curl -X PUT https://api.mintfax.com/v1/webhooks/we_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..." \
  -H "Content-Type: application/json" \
  -d '{
    "is_active": false
  }'
```

This is the right choice when the endpoint might come back. `DELETE` is one-way; `is_active: false` is not. Use [delivery attempts](/docs/webhooks/inspect-attempts) to confirm the pause took effect - the attempt list for a paused endpoint stops growing as new events fire.

## Delete an endpoint permanently

You are retiring the endpoint. The service that owned it is gone, or the URL is being reassigned to a new receiver. The new receiver should register its own endpoint with its own signing secret.

```bash theme={null}
curl -X DELETE https://api.mintfax.com/v1/webhooks/we_8aZqRm4yT3vK7pNxJ2bH9c \
  -H "Authorization: Bearer mfx_test_abc123def456..."
```

The response is `204 No Content`. The endpoint's id, secret, and subscription list are gone; there is no undo. If you might need the endpoint back, use `is_active: false` and delete it later.

## Related

* [Receive fax events with webhooks](/docs/webhooks/index) - register an endpoint in the first place
* [Verify webhook signatures](/docs/webhooks/verify-requests) - the signing secret concern (it is per-endpoint and does not change on URL update)
* [Debug webhook deliveries](/docs/webhooks/inspect-attempts) - confirm a pause or delete took effect