---
title: "Create Webhook"
method: POST
path: "/agents/webhooks"
tags: ["Webhooks"]
---

# Create Webhook

`POST /agents/webhooks`

Register a webhook endpoint. Cartesia POSTs [call events](/line/infrastructure/observability#webhooks) 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](/api-reference/agents/agents/update).

## Headers

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

## Request body

- CreateWebhookBody
  - `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`

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

- AgentWebhookResponse — 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.
  - `display_name` string, nullable — The webhook's display name, or `null` if unset.
  - `created_at` string, date-time, required — When the webhook was created.
  - `updated_at` string, date-time, required — When the webhook was last updated.

---

[API](https://skmtc.net/cartesia/apis/cartesia-api.md) · [All operations](https://skmtc.net/cartesia/apis/cartesia-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cartesia/cartesia-api/revisions/8910812440d3/schema)