> ## 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.
# Update Webhook
> Update a webhook endpoint.
Changes state - verify before retry
**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.
Updates a registered webhook subscription. You can change the delivery `url`, add or remove `events`, rotate the signing `secret`, or toggle `is_active` to temporarily pause delivery. Only the fields you include are updated, omitted fields keep their current values. The subscription's `id` does not change, so consumers can continue to reference the same webhook ID after the update.
## When to use this
* **URL change**: your consumer service moved to a new host or path.
* **Adding events**: you started building a feature that needs an additional event type and want it delivered to the existing endpoint.
* **Removing events**: your consumer no longer cares about a particular event and you want to stop the unnecessary deliveries.
* **Secret rotation**: your signing secret leaked, expired, or you are on a periodic rotation cadence.
* **Temporary pause**: you want to stop receiving events without losing the subscription. Set `is_active` to `false`, then back to `true` later. If you do not plan to re-enable, use [Delete Webhook](/docs/api-reference/v1/webhooks/delete) instead.
## Rotating the signing secret
The public contract does not promise a dual-secret overlap window. Rotate as if the new value can take effect immediately:
1. Update your consumer service to accept both the old and new secret during a transition window.
2. Send the new secret to DialNexa through this endpoint.
3. Confirm new deliveries are being verified with the new secret.
4. Remove the old secret from your consumer service.
See [Webhook secrets](/docs/api-access/webhook-secrets) for the verification format and helper code.
## Path parameters
| Parameter | Description |
| --------- | ----------------------------------------------- |
| `id` | The webhook ID, for example `whk_c9v3nz8rq4pm`. |
## Errors
* `404 Not Found` is returned when the webhook does not exist.
* `400 Bad Request` is returned when the URL is malformed or an event type is unknown.
## Related endpoints
* [List Webhooks](/docs/api-reference/v1/webhooks/list): review every webhook on the workspace.
* [Delete Webhook](/docs/api-reference/v1/webhooks/delete): permanently remove a subscription.
* [Webhook secrets](/docs/api-access/webhook-secrets): verification format.
* [Webhook retries and failures](/docs/api-access/webhook-retries-and-failures): how DialNexa handles delivery failures.
## OpenAPI
````yaml PATCH /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}:
patch:
tags:
- User Webhooks
- User Webhooks V1
- V1
summary: Update Webhook
description: Update URL, events, or active status. Partial updates supported.
operationId: UserWebhooksV1Controller_update
parameters:
- name: id
required: true
in: path
description: Webhook ID
schema:
type: string
example: webhook_abc123
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateUserWebhookDto'
examples:
request:
summary: Update a webhook
value:
is_active: false
responses:
'200':
description: Webhook updated successfully.
content:
application/json:
schema:
type: object
properties:
message:
type: string
example: Webhook updated successfully
webhook:
type: object
properties:
id:
type: string
example: webhook_abc123
url:
type: string
example: https://webhook.site/new-endpoint
events:
type: array
items:
type: string
example:
- call.completed
is_active:
type: boolean
example: false
examples:
success:
summary: Successful response
value:
id: webhook_abc123
url: https://example.com/dialnexa/webhook
events:
- call.completed
is_active: false
createdAt: '2026-07-03T10:30:00.000Z'
'400':
description: Bad request - invalid fields.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
error:
summary: 400 Bad Request
value:
statusCode: 400
message: url must be a valid URL
error: Bad Request
'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:
UpdateUserWebhookDto:
type: object
properties:
url:
type: string
example: https://webhook.site/updated-endpoint
description: The new URL for the webhook.
events:
example:
- order.paid
description: Updated list of events.
type: array
items:
type: string
is_active:
type: boolean
example: false
description: Whether the webhook is active.
secret:
type: string
example: newSecret
description: New secret for signing payloads.
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
````