Skip to navigation

Get webhook endpoint

Returns one endpoint with its URL, event types, status and failure counters. status is disabled when VoxAI stopped sending events to it, and disabled_reason says why. secret_rotation is set while the previous secret is still valid. The signing secret is never returned here: if you lost it, rotate it. Required scope: webhooks:manage. With a test key (vx_test_) it behaves exactly as with a live key and consumes nothing.

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:

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
429
Too Many Requests Error
500
Internal Server Error
503
Service Unavailable Error