> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.getvoxai.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.getvoxai.com/_mcp/server.

# Create webhook endpoint

POST https://api.getvoxai.com/v1/webhook-endpoints
Content-Type: application/json

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.

Reference: https://docs.getvoxai.com/api-reference/webhooks/create

## Authentication

- `Authorization` header (bearer token, required) — API key created by an Owner or Admin of the organization. Never in the query string.

## Request

### Headers

- `VoxAI-Version` (enum, optional) — API version for this request; defaults to the version the key is pinned to.
  - Allowed values: `2026-10-01`
- `Idempotency-Key` (string, required) — 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`.

### Body (application/json)

This endpoint expects an object.

- `url` (string, required) — 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`).
- `events` (list of string, required) — 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.
- `description` (string, optional) — A label for you, shown in the app.
- `include_transcript` (boolean, optional, default: false) — 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

### 201

Created.

- `object` ("webhook_endpoint", required) — Always `webhook_endpoint`.
- `id` (string, required) — Id of the endpoint: use it in `GET /webhook-endpoints/{endpoint_id}` and in the other endpoint operations.
- `url` (string, required) — Where VoxAI sends the events.
- `description` (string, required, nullable) — The label you gave to the endpoint; `null` if it has none.
- `events` (list of string, required) — The event types the endpoint receives, by name (see `GET /webhook-event-types`).
- `include_transcript` (boolean, required) — `true` if `call.ended` and `call.analyzed` carry the transcript.
- `status` (enum, required) — `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: `active`, `paused`, `disabled`
- `disabled_reason` (enum, required) — 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: `repeated_failures`, `platform`
- `api_version` (string, required) — The version of the event envelope this endpoint receives (a date).
- `secret_rotation` (WebhookEndpointsPostResponsesContentApplicationJsonSchemaSecretRotation, required, nullable) — Set while the previous secret is still valid (every delivery carries two signatures).
- `last_success_at` (datetime, required, nullable) — When your server last answered a delivery with a 2xx status, ISO 8601 UTC; `null` if it never did.
- `consecutive_failures` (integer, required) — 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_at` (datetime, required) — When the endpoint was created, ISO 8601 UTC.
- `simulated` (boolean, required) — true with a test key: nothing was created and the id does not exist.
- `secret` (string, required, nullable) — 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.

## Errors

### 400 Bad Request Error

Possible errors: * `invalid_api_version`: The `VoxAI-Version` header names a version that does not exist. Use one of the versions listed in the `VoxAI-Version` parameter, or omit the header to use the version the key is pinned to. * `invalid_request`: The path, query or body does not match the schema of the operation: a missing or unknown field, a wrong type, a value out of range. Fix the request. `details` lists each problem as `{ location, path, message }`: `location` is `params`, `query` or `body` and `path` points to the field.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 401 Unauthorized Error

Possible errors: - `invalid_api_key`: The `Authorization` header is missing, malformed, or carries a key that does not exist, was revoked or has expired. Send `Authorization: Bearer vx_live_…` (or `vx_test_…`) with an active key. Create a new key in the app if this one expired.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 403 Forbidden Error

Possible errors: - `feature_not_available`: The plan of the organization does not include the API, or the feature this operation needs. Upgrade the plan in the app. Reads and deletions stay available after a downgrade. - `insufficient_scope`: The key does not have the scope this operation requires (written in the description of the operation). Create a key with the required scope (an Owner or Admin can do it in the app), or ask for the scope to be added. - `ip_not_allowed`: The key has an IP allow-list and the request comes from an address that is not on it. Call from an allowed address, or add this address to the key in the app. - `organization_suspended`: The organization that owns the key is suspended. Contact the organization Owner: nothing can be done through the API until the organization is active again.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 409 Conflict Error

Possible errors: * `idempotency_outcome_unknown`: A previous request with this `Idempotency-Key` failed with a `429`, a `5xx` or a temporary `409` inside a NOT retriable operation, or was interrupted with no response, so its outcome is not known and it is never run again with the same key. Read the state of the resource (for example `GET /outbound-calls/{outbound_call_id}` or the list) and retry with a NEW key only if the operation did not happen. * `license_not_active`: The organization has no active plan (for example it expired). Renew the plan in the app. * `request_in_progress`: A request with the same `Idempotency-Key` is still running. Wait a few seconds and retry with the same key: you will get the outcome of the first request. * `too_many_webhook_endpoints`: The organization reached the maximum number of webhook endpoints. Delete an endpoint before creating another.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 422 Unprocessable Entity Error

Possible errors: - `idempotency_key_reused`: The same `Idempotency-Key` was already used in the last 24 hours with a different request (other operation, path or body). Use a new key for a new request. Reuse a key only to repeat exactly the same request. - `invalid_webhook_url`: The URL is not a public `https` address, or it contains credentials or a fragment (`details.reason`). Use a public `https` URL without user, password or `#fragment`. - `unknown_event_type`: One of the event types does not exist, or is reserved and not emitted yet. Use the names in `details.event_types` (see `GET /webhook-event-types`).

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 429 Too Many Requests Error

Possible errors: - `rate_limited`: Too many requests: over the per-minute limit of this key or of the whole organization (see `rate_limits` in `GET /me`), or over a limit of the operation itself, such as the hourly limit on webhook tests and resends. Wait for the number of seconds in the `Retry-After` header, then retry. Spread requests over time.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 500 Internal Server Error

Possible errors: - `internal_error`: An unexpected error on our side. Retry once after a few seconds. For writes marked as retriable, retry with the same `Idempotency-Key`, so the operation is never done twice; for the other writes, first read the state of the resource, then retry with a NEW key only if the operation did not happen. If it persists, contact support with the `requestId`.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

### 503 Service Unavailable Error

Possible errors: - `api_not_configured`: The API is not enabled on this service. Contact support. - `webhooks_not_configured`: Webhooks are not enabled on this service. Contact support.

- `error` (string, required) — Human-readable message in English.
- `code` (string, required) — Stable machine-readable code; decide what to do from this, never from the message.
- `requestId` (string, required) — Same value as the X-Request-Id response header; quote it when contacting support.
- `details` (any, optional) — Extra information, only on some codes. For `invalid_request` it is a list of `{ location, path, message }`, one per field (`location` is `params`, `query` or `body`) with a problem; for the other codes its fields depend on the code (for example `details.limit`).

## Types

### WebhookEndpointsPostResponsesContentApplicationJsonSchemaSecretRotation

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

- `previous_expires_at` (datetime, required) — ISO 8601, UTC.

## Examples

**Request**

```json
{
  "url": "https://example.com/hooks/voxai",
  "events": [
    "call.ended",
    "call.analyzed"
  ],
  "description": "CRM sync",
  "include_transcript": false
}
```

**Response**

```json
{
  "object": "webhook_endpoint",
  "id": "3b9e5a71-6c2d-4f48-b0a3-8d1e7c4f2a96",
  "url": "https://example.com/hooks/voxai",
  "description": "CRM sync",
  "events": [
    "call.ended",
    "call.analyzed"
  ],
  "include_transcript": false,
  "status": "active",
  "disabled_reason": null,
  "api_version": "2026-10-01",
  "secret_rotation": null,
  "last_success_at": null,
  "consecutive_failures": 0,
  "created_at": "2026-11-16T10:00:00Z",
  "simulated": false,
  "secret": "whsec_EXAMPLE-ONLY-not-a-real-secret-000000000000"
}
```

**SDK Code**

```python
import requests

url = "https://api.getvoxai.com/v1/webhook-endpoints"

payload = {
    "url": "https://example.com/hooks/voxai",
    "events": ["call.ended", "call.analyzed"],
    "description": "CRM sync",
    "include_transcript": False
}
headers = {
    "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.getvoxai.com/v1/webhook-endpoints';
const options = {
  method: 'POST',
  headers: {
    'Idempotency-Key': '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: '{"url":"https://example.com/hooks/voxai","events":["call.ended","call.analyzed"],"description":"CRM sync","include_transcript":false}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.getvoxai.com/v1/webhook-endpoints"

	payload := strings.NewReader("{\n  \"url\": \"https://example.com/hooks/voxai\",\n  \"events\": [\n    \"call.ended\",\n    \"call.analyzed\"\n  ],\n  \"description\": \"CRM sync\",\n  \"include_transcript\": false\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.getvoxai.com/v1/webhook-endpoints")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Idempotency-Key"] = '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58'
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"url\": \"https://example.com/hooks/voxai\",\n  \"events\": [\n    \"call.ended\",\n    \"call.analyzed\"\n  ],\n  \"description\": \"CRM sync\",\n  \"include_transcript\": false\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.getvoxai.com/v1/webhook-endpoints")
  .header("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"url\": \"https://example.com/hooks/voxai\",\n  \"events\": [\n    \"call.ended\",\n    \"call.analyzed\"\n  ],\n  \"description\": \"CRM sync\",\n  \"include_transcript\": false\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.getvoxai.com/v1/webhook-endpoints', [
  'body' => '{
  "url": "https://example.com/hooks/voxai",
  "events": [
    "call.ended",
    "call.analyzed"
  ],
  "description": "CRM sync",
  "include_transcript": false
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
    'Idempotency-Key' => '3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.getvoxai.com/v1/webhook-endpoints");
var request = new RestRequest(Method.POST);
request.AddHeader("Idempotency-Key", "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58");
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"url\": \"https://example.com/hooks/voxai\",\n  \"events\": [\n    \"call.ended\",\n    \"call.analyzed\"\n  ],\n  \"description\": \"CRM sync\",\n  \"include_transcript\": false\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Idempotency-Key": "3f1c9a72-5d4e-4b8a-9c6f-0e2d7a1b4c58",
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "url": "https://example.com/hooks/voxai",
  "events": ["call.ended", "call.analyzed"],
  "description": "CRM sync",
  "include_transcript": false
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.getvoxai.com/v1/webhook-endpoints")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```