Create webhook endpoint
Creates an endpoint that receives the events you choose and returns it with its signing secret, whsec_ plus 43 characters. The secret is in this response ONLY: store it now, and if you lose it rotate it. The URL must be a public https address on port 443, without credentials or fragment; it is checked now and again at every delivery. A key can subscribe only to events whose read scope it has, and include_transcript needs calls:read. Every event is a POST with a JSON body { id, object: "event", type, api_version, created_at, organization_id, data: { object } }, signed with the secret of the endpoint. The VoxAI-Signature header is t=<unix seconds>,v1=<hex>: v1 is the HMAC-SHA256, in hex, of <t>.<raw request body>, and the key is the whole secret string (whsec_ included) in UTF-8. Compute it on the raw bytes you received, not on JSON you serialized again, compare it in constant time, and reject a message whose t is more than 5 minutes away from your clock. While a secret is being rotated the header carries two v1 values: accept the event if either matches. Other headers are VoxAI-Event-Id, VoxAI-Event-Type, VoxAI-Delivery-Id and VoxAI-Delivery-Attempt. Answer with a 2xx status within 10 seconds: any other status, a timeout or a redirect (not followed) is a failure, and the delivery is tried again, up to 8 attempts over about 24 hours. Events arrive at least once, so use the event id to ignore repeats. After at least 10 deliveries in a row that failed for good and no success for 3 days, the endpoint is disabled. Creating needs an active plan that includes webhooks (otherwise 409 license_not_active), and there is a maximum number of endpoints per organization (409 too_many_webhook_endpoints). With a test key nothing is created and secret is null. Required scope: webhooks:manage. With a test key (vx_test_) it is simulated: nothing real happens and nothing is billed. Requires an Idempotency-Key header. NOT retriable: when the operation itself fails with a 429, a 5xx or a temporary 409, the outcome is uncertain and the key becomes “unknown” (the same key gives 409 idempotency_outcome_unknown); with no response at all, the same key returns the first outcome or that same 409. After idempotency_outcome_unknown, read the state of the resource and retry with a new key only if the operation did not happen. 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
Headers
API version for this request; defaults to the version the key is pinned to.
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
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).
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.
Add the transcript to call.ended and call.analyzed (off by default: it is the most personal data we keep). Needs the calls:read scope. A body above 256 KiB is sent without the transcript and with transcript_omitted: "too_large".
Response
Always webhook_endpoint.
Id of the endpoint: use it in GET /webhook-endpoints/{endpoint_id} and in the other endpoint operations.
The label you gave to the endpoint; null if it has none.
The event types the endpoint receives, by name (see GET /webhook-event-types).
true if call.ended and call.analyzed carry the transcript.
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).
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.
The version of the event envelope this endpoint receives (a date).
Set while the previous secret is still valid (every delivery carries two signatures).
When your server last answered a delivery with a 2xx status, ISO 8601 UTC; null if it never did.
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.
true with a test key: nothing was created and the id does not exist.
The signing secret, whsec_ plus 43 characters. Shown ONLY in this response: store it now. Lost? Rotate it. The HMAC key is the whole string, in UTF-8. Every delivery is signed: the VoxAI-Signature header is t=<unix seconds>,v1=<hex>, where v1 is the HMAC-SHA256 (hex) of <t>.<raw request body> with this secret. During a rotation there are two v1 values and one valid match is enough. null with a test key.