# Delete a webhook

DELETE /v1/webhooks/{webhook_id}

Source: https://cherami.to/docs/api/webhooks/delete-webhook



{/* Generated from apps/web/openapi. Edit the contract, not this file. */}

`DELETE /v1/webhooks/{webhook_id}`

Requires an [API key](https://cherami.to/docs/api#authentication): `Authorization: Bearer YOUR_CREDENTIAL`.

Deletes the webhook. `status: "deleted"` means the provider endpoint is gone; `"pending"` means removal was recorded and will be completed in the background, during which the webhook reads as pending and can be deleted again safely.

Deletion stops future delivery and is the only way to change a URL: add the replacement first if you need continuity. The ID is never reused. Missing and other-account webhooks return `404`. Delivery history for the deleted webhook is no longer readable through its ID; the [event view](https://cherami.to/docs/api/webhooks/get-webhook-event) still lists its past attempts with a null `webhook_id`.

## Parameters [#parameters]

| Parameter    | Location | Required | Type   | Meaning                                        |
| ------------ | -------- | -------- | ------ | ---------------------------------------------- |
| `webhook_id` | path     | Yes      | string | Owned Cherami resource ID returned by the API. |

## curl example [#curl-example]

Replace resource-ID placeholders with returned IDs. Supply `CHERAMI_API_KEY` through your private shell environment.

```sh
curl --silent --show-error --include --request DELETE \
  "https://cherami.to/v1/webhooks/WEBHOOK_ID" \
  --header "Authorization: Bearer $CHERAMI_API_KEY"
```

## Responses [#responses]

### HTTP 200 [#http-200]

Successful operation; inspect resource state and outcome fields.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[WebhookDeletion](#schema-webhookdeletion)

```json
{
  "id": "11111111-1111-4111-8111-111111111111",
  "status": "deleted"
}
```

### HTTP 401 [#http-401]

`unauthorized`: Provide a valid bearer credential. Use [human-approved recovery](https://cherami.to/docs/guides/recovery) if access is lost.

* `X-Request-ID`: Support correlation ID, not an idempotency key.
* `WWW-Authenticate`: `"Bearer"`

Content type: `application/json`.

[Error](#schema-error)

### HTTP 404 [#http-404]

`not_found`: Resource is absent or inaccessible to this account. Reply targets must be in the sending inbox.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 409 [#http-409]

`webhook_operation_in_progress`: Another change to this webhook is in flight. Retry after a minute; read the webhook first if an earlier change was uncertain.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

### HTTP 503 [#http-503]

`webhooks_unavailable`: Webhook management is unavailable or the operation's outcome is unknown. Read or list webhooks before repeating a change; adding again can create a duplicate.

* `X-Request-ID`: Support correlation ID, not an idempotency key.

Content type: `application/json`.

[Error](#schema-error)

## Schema: WebhookDeletion [#schema-webhookdeletion]

deleted: the provider endpoint is gone. pending: removal is recorded and finishes in the background; the webhook no longer delivers new work once removed at the provider.

| Field    | Required | Type                       | Meaning and constraints                                                        |
| -------- | -------- | -------------------------- | ------------------------------------------------------------------------------ |
| `id`     | Yes      | string                     | Cherami resource ID, distinct from the RFC Message-ID. Use the returned value. |
| `status` | Yes      | `"deleted"` or `"pending"` |                                                                                |

## Schema: Error [#schema-error]

| Field   | Required | Type   | Meaning and constraints |
| ------- | -------- | ------ | ----------------------- |
| `error` | Yes      | object |                         |

### `error` fields [#error-fields]

| Field     | Required | Type   | Meaning and constraints                                                                       |
| --------- | -------- | ------ | --------------------------------------------------------------------------------------------- |
| `code`    | Yes      | string | Programmatic error code. Handle unrecognized codes by status and operation-specific recovery. |
| `message` | Yes      | string | Human-readable context, not a stable string to match.                                         |

[HTTP conventions, errors and pagination](https://cherami.to/docs/api/errors) · [Download OpenAPI 3.1](https://cherami.to/openapi.json)