> ## Documentation Index
> Fetch the complete documentation index at: https://dialnexa.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Delete Webhook
> Delete a webhook endpoint.
Destructive
**Recommended.** This endpoint is part of the public `/v1` API reference and is the supported path for new integrations. See the [migration guide](/docs/api-reference/v1/migrating-to-v1) for versioning guidance.
Soft-deletes a webhook subscription so new events stop being delivered to the registered URL. This action is destructive from the public API's perspective, and the secret is not recoverable. If you create another subscription later, store its secret and update your verification configuration.
## When to use this
Webhook deletion is destructive. Reach for it only when you want to permanently retire a subscription, for example:
* A consumer service is being decommissioned.
* The URL was registered against a development environment that no longer exists.
* A previous integration leaked the signing secret and the cleanest mitigation is to delete the subscription, rotate any external dependencies on it, and re-register with a new secret.
If you only want to stop receiving events temporarily, use [Update Webhook](/docs/api-reference/v1/webhooks/update) and set `is_active` to `false`. Disabled webhooks keep their secret and event subscriptions, so you can re-enable delivery later without coordinating a redeploy.
## Verify deletion
List webhooks and confirm the deleted ID is no longer returned. If the delete request times out, check the list before repeating it. The public contract does not currently guarantee how already queued delivery attempts are handled, so keep the receiver safe to run during the transition.
## Path parameters
| Parameter | Description |
| --------- | ----------------------------------------------- |
| `id` | The webhook ID, for example `whk_c9v3nz8rq4pm`. |
## Errors
* `404 Not Found` is returned when the webhook does not exist or has already been deleted.
* `403 Forbidden` is returned when the caller's API key does not have webhook management permission.
## Related endpoints
* [Update Webhook](/docs/api-reference/v1/webhooks/update): pause delivery without deleting the subscription.
* [List Webhooks](/docs/api-reference/v1/webhooks/list): confirm the webhook is gone after deletion.
* [Webhook secrets](/docs/api-access/webhook-secrets): how secrets are generated and rotated.
## OpenAPI
````yaml DELETE /v1/user-webhooks/{id}
openapi: 3.0.0
info:
title: DialNexa API
description: >-
Public REST API for the DialNexa voice AI platform. Versioned endpoints are
under /v1; unversioned endpoints are legacy and deprecated.
version: 1.0.0
servers:
- url: https://api.dialnexa.com
description: DialNexa production API
security:
- bearer: []
tags:
- name: API Keys
- name: Agent Functions
- name: Agents V1
- name: Agents2
- name: Batch Calls
- name: Batch Calls V1
- name: Call Logs
- name: Calls
- name: Calls V1
- name: Campaign Leads
- name: Campaigns
- name: External Webhooks
- name: Knowledge Base
- name: Knowledge Base V1
- name: LLMs
- name: LLMs V1
- name: Languages
- name: Languages V1
- name: Organization Phone Numbers
- name: Organization Phone Numbers V1
- name: Phone Number Pricing
- name: Phone Number Pricing V1
- name: Transcribers
- name: Transcribers V1
- name: User Webhooks
- name: User Webhooks V1
- name: V1
- name: Voices
- name: Voices V1
- name: Webcall
- name: Workflow Leads
- name: Workflow Leads V1
- name: Workflows
- name: Workflows V1
paths:
/v1/user-webhooks/{id}:
delete:
tags:
- User Webhooks
- User Webhooks V1
- V1
summary: Delete Webhook
description: Soft-deletes the webhook. Events will stop being delivered immediately.
operationId: UserWebhooksV1Controller_remove
parameters:
- name: id
required: true
in: path
description: Webhook ID
schema:
type: string
example: webhook_abc123
responses:
'200':
description: Webhook deleted successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Webhook deleted successfully
id:
type: string
example: webhook_abc123
examples:
success:
summary: Successful response
value:
success: true
message: Webhook deleted successfully
'401':
description: Unauthorized - missing or invalid API key.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 401 Unauthorized
value:
statusCode: 401
message: API key is missing or invalid
error: Unauthorized
'403':
description: Forbidden - API key does not have access to this organization.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 403 Forbidden
value:
statusCode: 403
message: You do not have permission to access this resource
error: Forbidden
'404':
description: Webhook not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 404 Not Found
value:
statusCode: 404
message: Webhook not found
error: Not Found
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 500 Internal Server Error
value:
statusCode: 500
message: Internal server error
error: Internal Server Error
security:
- bearer: []
components:
schemas:
ErrorResponse:
type: object
properties:
statusCode:
type: integer
example: 400
message:
oneOf:
- type: string
- type: array
items:
type: string
example: phone_number must be a valid E.164 phone number
error:
type: string
example: Bad Request
required:
- statusCode
- message
- error
securitySchemes:
bearer:
scheme: bearer
bearerFormat: JWT
type: http
````