---
id: webhooks-delete
slug: /apis/webhooks/delete
title: 'Delete a Subscription'
description: 'Delete a webhook subscription with POST ~/api/webhook/delete/:id — note the verb and the path shape.'
sidebar_label: 'Delete'
sidebar_position: 7
tags: ['api', 'webhooks', 'delete']
---

## Request

```text
POST ~/api/webhook/delete/:id
```

:::danger This is a `POST`, and `delete` comes before the id
Two things are surprising here, and both are real:

1. **The verb is `POST`, not `DELETE`.** These APIs accept only `GET` and `POST`; sending
   `DELETE ~/api/webhook/:id` returns `405 Method Not Allowed`.
2. **`delete` is a path segment before the id.** It is `/api/webhook/delete/:id`, not
   `/api/webhook/:id/delete`.

Getting the path shape wrong is worse than getting the verb wrong: `POST ~/api/webhook/:id` is
the **[update](/apis/webhooks/update) endpoint**, so a mis-formed delete will not fail — it will
succeed as an update, quietly overwriting the subscription with whatever body you sent
(or with an empty configuration if you sent none).

:::

`:id` is the **server-assigned UUID** from
[create](/apis/webhooks/create#response), not your `webhookId`.

```bash title="Request"
curl -X POST "https://{host}/{instance}/api/webhook/delete/336d997f-d9fa-4612-80e8-9f41a4b41352" \
  -H "Authorization: Bearer <access-token>" \
  -H "Accept: application/json"
```

No request body is required.

## Response

The deleted subscription is returned, so you have a record of what was removed:

```json title="200 OK"
{
  "id": "336d997f-d9fa-4612-80e8-9f41a4b41352",
  "webhookId": "Webhook identifier",
  "url": "https://externalsystem.com",
  "description": "Short description of the webhook subscription",
  "enabled": true,
  "eventTypes": [],
  "lastResponseAt": "0001-01-01T00:00:00Z",
  "retryCount": 0,
  "createdAt": "2018-09-27T20:28:41.3829451Z",
  "updatedAt": "2018-09-27T20:28:41.3829451Z",
  "createdBy": "Member:20"
}
```

Keep this response if you might need to recreate the subscription. Note that
`authorizationHeader` and `secret` are **not** included — they are write-only, so restoring a
deleted subscription requires your own copy of those values.

## Delete Versus Disable

Deleting is usually the wrong tool for "stop these notifications for now". Prefer
[`"enabled": false`](/apis/webhooks/update) — it preserves the id, the event type definitions
and the credentials, and it is a one-field change to reverse.

Delete when the integration is genuinely retired.

## Deleting Every Subscription

```text
POST ~/api/webhook/delete
```

The same route with **no id** deletes subscriptions in bulk.

:::danger This deletes every subscription in the instance
`POST ~/api/webhook/delete` marks **all** webhook subscriptions in the instance as deleted. It
is not scoped to the subscriptions you created, and it is not scoped to a project — it iterates
every subscription in the registry.

Every integration in the instance stops receiving events, including ones owned by other teams.
There is no confirmation step and no bulk undo.

Note how close it is to the single-subscription form: omitting the id — a trailing-slash bug, an
empty variable in a URL template — turns "delete this one" into "delete them all". Guard against
an empty id in client code before the request is built.

This route was undocumented in the published reference material.
:::

If you need it, capture the full list first with [query](/apis/webhooks/query) so you can
reconstruct.

## Related Topics

- [Update a subscription](/apis/webhooks/update) — disable rather than delete
- [Query subscriptions](/apis/webhooks/query)
- [Errors](/apis/conventions/errors) — why `DELETE` returns `405`