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

# Delete Webhook

> Delete a webhook subscription — deliveries stop immediately and the delivery history is removed.

Deletes a webhook subscription. Deliveries stop immediately and the subscription's delivery history is removed with it. Deletion is permanent — there is no undo.

This is also the recovery path for two situations:

* **Lost secret:** secrets are shown only once at [creation](/docs/developers/api-reference/webhooks/create). Delete the subscription and create a new one to get a fresh `whsec_…` secret (this is also how you rotate a secret).
* **Auto-disabled subscription:** a `DISABLED` webhook cannot be re-enabled. Delete it, fix your endpoint, and [create](/docs/developers/api-reference/webhooks/create) a replacement — then catch up on events missed while disabled with [`GET /updates`](/docs/developers/api-reference/updates/poll), since new subscriptions have no backfill.

**Requirements:** `webhooks:manage` scope + the `public_api_webhooks` feature.

## Request

<ParamField path="webhookId" type="string" required>
  The webhook subscription ID.
</ParamField>

## Response

<ResponseField name="webhook" type="object">
  The subscription as it existed at deletion: `{id, url, eventTypes, status, createdAt, disabledAt, disabledReason}` — same shape as [`GET /webhooks/{id}`](/docs/developers/api-reference/webhooks/get).
</ResponseField>

<ResponseField name="deleted" type="boolean">
  Always `true` on success.
</ResponseField>

## Errors

| Status | `code`         | Meaning                                                                                          |
| ------ | -------------- | ------------------------------------------------------------------------------------------------ |
| `401`  | `UNAUTHORIZED` | Missing or invalid token                                                                         |
| `403`  | `FORBIDDEN`    | Missing `webhooks:manage` scope, or `public_api_webhooks` disabled                               |
| `404`  | `NOT_FOUND`    | No such webhook, or it belongs to another account (`details: {resource: "webhooks", webhookId}`) |

<RequestExample>
  ```bash curl theme={null}
  curl -sS -X DELETE https://app.opentrain.ai/api/public/v1/webhooks/<WEBHOOK_ID> \
    -H "Authorization: Bearer $OT_API_TOKEN"
  ```

  ```bash CLI theme={null}
  opentrain webhooks delete <WEBHOOK_ID> --json
  ```

  ```json MCP: opentrain_delete_webhook theme={null}
  {
    "webhookId": "<WEBHOOK_ID>"
  }
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "webhook": {
      "id": "<WEBHOOK_ID>",
      "url": "https://example.com/hooks/opentrain",
      "eventTypes": ["proposal.received", "message.received", "approval.confirmed"],
      "status": "ACTIVE",
      "createdAt": "2026-06-12T10:00:00.000Z",
      "disabledAt": null,
      "disabledReason": null
    },
    "deleted": true
  }
  ```

  ```json 404 theme={null}
  {
    "error": "Webhook not found",
    "code": "NOT_FOUND",
    "requestId": "<REQUEST_ID>",
    "details": {
      "resource": "webhooks",
      "webhookId": "<WEBHOOK_ID>"
    }
  }
  ```
</ResponseExample>