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

# Permanently Delete a Webhook Subscription by Its ID

> DELETE /v1/webhook-subscriptions/{id} — Permanently removes a webhook subscription and stops all event delivery immediately. Cannot be undone.

Deleting a webhook subscription immediately and permanently stops event delivery to the associated endpoint. The subscription record, its signing secret, and all associated configuration are removed from Diameter's systems. In-flight delivery attempts that have not yet completed will be abandoned. This action cannot be undone — to temporarily halt delivery instead, consider setting `isActive` to `false` via the [Update Subscription](https://diameterpay.mintlify.site/api-reference/webhooks/update-subscription.md) endpoint.

> [!WARNING]
>
> **This action is irreversible.** The subscription's signing secret is invalidated immediately upon deletion. Any webhook deliveries currently in-flight will be abandoned. If you need to stop deliveries temporarily, use the Update Subscription endpoint to set `isActive: false` instead.

## Endpoint

```
DELETE /v1/webhook-subscriptions/{id}
```

**Required scope:** `webhooks.delete`

## Request Headers

| Header | Required | Description |
| - | - | - |
| `Authorization` | Yes | `Bearer {access_token}` |

## Path Parameters

**id** `string` *required*

The UUID of the webhook subscription to permanently delete.

## Response — 204 No Content

A successful deletion returns HTTP `204 No Content` with an empty response body.

## Examples

### Delete a subscription

```bash theme={null}
curl --request DELETE \
  --url https://api.diameterpay.com/v1/webhook-subscriptions/3fa85f64-5717-4562-b3fc-2c963f66afa6 \
  --header 'Authorization: Bearer {access_token}'
```

### Response

```
HTTP/1.1 204 No Content
```

## Error Responses

| Status | Description |
| - | - |
| `404 Not Found` | No subscription with the given `id` exists for your tenant. |
| `403 Forbidden` | Your token does not have the `webhooks.delete` scope. |

## What Happens After Deletion

* Event delivery to the registered URL stops immediately.
* The signing secret is invalidated; any signature checks using the old secret will fail.
* The subscription no longer appears in [List Subscriptions](https://diameterpay.mintlify.site/api-reference/webhooks/list-subscriptions.md) results.
* Historical webhook events associated with this subscription remain queryable via the [Search Events](https://diameterpay.mintlify.site/api-reference/webhooks/search-events.md) endpoint.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.