Skip to main content
POST
/
agents
/
webhooks
cURL
curl -X POST "https://api.cartesia.ai/agents/webhooks" \
  -H "X-API-Key: your-api-key" \
  -H "Cartesia-Version: 2026-03-01" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-server.example/webhooks/cartesia",
    "secret": "YOUR_WEBHOOK_SECRET"
  }'
{
  "id": "<string>",
  "url": "<string>",
  "secret": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z",
  "display_name": "<string>"
}

Authorizations

​
Authorization
string
header
required

Cartesia API key (sk_car_...). Get one at play.cartesia.ai/keys.

Headers

​
Cartesia-Version
enum<string>
required

API version header.

Available options:
2026-03-01
Example:

"2026-03-01"

Body

application/json
​
url
string<uri>
required

The HTTPS endpoint Cartesia POSTs call events to.

​
secret
string
required

A shared secret. Cartesia returns it in the X-Webhook-Secret header on every delivery so your endpoint can verify the request.

​
display_name
string

An optional name to identify the webhook.

Response

200 - application/json

Webhook created. The response includes the secret — this is the only time it is returned.

A webhook including its secret. The secret is only returned when the webhook is created.

​
id
string
required

The ID of the webhook.

​
url
string<uri>
required

The HTTPS endpoint call events are delivered to.

​
secret
string
required

The shared secret. Returned only on creation.

​
created_at
string<date-time>
required

When the webhook was created.

​
updated_at
string<date-time>
required

When the webhook was last updated.

​
display_name
string | null

The webhook's display name, or null if unset.