Skip to navigation

Update webhook endpoint

Changes any of the URL, label, event types and transcript option of an endpoint, or pauses it (status: paused) and turns it on again (status: active), and returns the endpoint. Send only the fields to change; at least one is required. A paused endpoint receives no events and none are queued while it is paused. status: active also turns on an endpoint that VoxAI disabled for repeated failures, and restarts its failure counters, but not one disabled by VoxAI staff (403 webhook_endpoint_disabled_by_platform). To change an endpoint your key needs the read scope of every event family it receives, before and after the change. Pausing works even when the plan no longer includes webhooks; every other change needs an active plan that includes them. Required scope: webhooks:manage. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Accepts an optional Idempotency-Key header. Retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the key is released and a retry with the same key runs the operation again; with no response at all, a retry with the same key returns the first outcome or runs the operation again. A 429 rate_limited from the request limit and 409 request_in_progress come before the operation and leave the key as it is: retry with the same key.

Authentication

AuthorizationBearer
API key created by an Owner or Admin of the organization. Never in the query string.

Path parameters

endpoint_idstringRequiredformat: "uuid"

Id of the webhook endpoint, as returned when it was created or by GET /webhook-endpoints.

Headers

VoxAI-VersionenumOptional

API version for this request; defaults to the version the key is pinned to.

Allowed values:
Idempotency-KeystringOptionalformat: "^[A-Za-z0-9_-]{16,64}$"

A unique value you generate for each new operation (16 to 64 letters, digits, hyphen or underscore; a UUID works). Repeating the same request with the same key within 24 hours returns the first response and does nothing again, when that response was a success or a 4xx error the same request would always get again (not 429, and not the temporary 409 codes request_in_progress, caller_has_active_call and caller_request_in_progress: for those, and for a 5xx, see the note on retrying in the operation); the same key with a different request is refused with idempotency_key_reused.

Request

This endpoint expects an object.
urlstringOptional1-4096 characters

Where VoxAI sends the events. It must be a public https URL on port 443, at most 2048 characters, with no credentials and no fragment. It is checked now and again at every delivery: an address in a private network is refused (invalid_webhook_url, details.reason).

descriptionstring or nullOptional1-200 characters

null removes the label.

eventslist of stringsOptional

The event types to receive, by name (see GET /webhook-event-types). Never *: a type that does not exist, or that is reserved and not emitted yet, gives 422 unknown_event_type. To subscribe to a type the key needs the read scope of its family.

include_transcriptbooleanOptional

Whether call.ended and call.analyzed carry the transcript. Turning it on needs the calls:read scope. Omit it to keep the current value.

statusenumOptional

paused: events are not queued while paused. active reactivates the endpoint, one disabled for repeated_failures included (its failure counters restart from zero); one disabled by VoxAI staff cannot be reactivated here.

Allowed values:

Response

Successful response.
object"webhook_endpoint"

Always webhook_endpoint.

idstringformat: "uuid"

Id of the endpoint: use it in GET /webhook-endpoints/{endpoint_id} and in the other endpoint operations.

urlstring
Where VoxAI sends the events.
descriptionstring or null

The label you gave to the endpoint; null if it has none.

eventslist of strings

The event types the endpoint receives, by name (see GET /webhook-event-types).

include_transcriptboolean

true if call.ended and call.analyzed carry the transcript.

statusenum

active: events are delivered. paused: you paused it, no events are queued. disabled: VoxAI stopped it, see disabled_reason; PATCH it with status: active to turn it on again, unless the reason is platform (403 webhook_endpoint_disabled_by_platform: contact support).

Allowed values:
disabled_reasonenum

Why the endpoint is disabled; null otherwise. repeated_failures: VoxAI disabled it after at least 10 failed deliveries in a row and no success for 3 days. platform: disabled by VoxAI staff.

Allowed values:
api_versionstring

The version of the event envelope this endpoint receives (a date).

secret_rotationobject or null

Set while the previous secret is still valid (every delivery carries two signatures).

last_success_atdatetime or null

When your server last answered a delivery with a 2xx status, ISO 8601 UTC; null if it never did.

consecutive_failuresinteger>=0

Deliveries in a row that failed for good, after all their attempts. A success resets it to 0; a test or a resend never adds to it.

created_atdatetime
When the endpoint was created, ISO 8601 UTC.
simulatedboolean

true with a test key: nothing was created and the id does not exist.

Errors

400
Bad Request Error
401
Unauthorized Error
403
Forbidden Error
404
Not Found Error
409
Conflict Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error