Webhooks

Create Webhook

Register a webhook endpoint. Cartesia POSTs call events to its url for every agent the webhook is attached to. Attach a webhook to an agent by setting the agent's webhook_id with Update Agent.

post/agents/webhooks

Request

Base URL
https://api.cartesia.ai
Auth
HTTP bearer
TypeScript
https://skmtc.dev/cartesia/apis/cartesia-api/docs/agents/webhooks/post.ts
A function with typed inputs. Its response is checked against the schema.

Headers

Cartesia-Version'2026-03-01' date required

Example:2026-03-01

API version header.

Request body

urlstring uri required

The HTTPS endpoint Cartesia POSTs call events to.

secretstring required

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

display_namestring

An optional name to identify the webhook.

Response

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

idstring required

The ID of the webhook.

urlstring uri required

The HTTPS endpoint call events are delivered to.

secretstring required

The shared secret. Returned only on creation.

display_namestring nullable

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

created_atstring date-time required

When the webhook was created.

updated_atstring date-time required

When the webhook was last updated.

Changes

No recorded changes to this operation across all 1 revision of this API.