---
title: "Create a webhook endpoint"
method: POST
path: "/webhook-endpoints"
tags: ["Webhooks"]
---

# Create a webhook endpoint

`POST /webhook-endpoints`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/webhook-endpoints`
- Auth: HTTP bearer

Creates an enabled Board-owned webhook endpoint and returns the signing secret once. The endpoint immediately receives the selected supported V1 event types. The secret is returned only on the original response and is not replayed by an idempotent retry — recover a lost secret by rotating.

## Request body

- CreateWebhookEndpointBody
  - `url` string, uri, required: Public HTTPS URL that will receive webhook deliveries.
  - `event_types` string[], required: V1 event types this endpoint subscribes to (unique).

## Response `201`

Endpoint created; secret returned once.

- WebhookEndpointCreated
  - `id` string, required
  - `object` 'webhook_endpoint', required
  - `url` string, required
  - `event_types` string[], required
  - `status` 'enabled' | 'paused' | 'failing', required
  - `failure_streak` integer, required
  - `last_failure_at` string, nullable, required
  - `last_success_at` string, nullable, required
  - `health_changed_at` string, nullable, required
  - `health_reason` 'consecutive_failures' | 'retry_exhausted' | 'http_410' | 'operator_pause' | 'operator_resume' | 'synthetic_recovery', nullable, required
  - `secret_overlap_expires_at` string, nullable, required
  - `created_at` string, required
  - `updated_at` string, required
  - `secret` string, required: Signing secret returned exactly once on create or rotate. Store it immediately.

## Other responses

- `400`: Invalid URL or event types.
- `402`: The board's plan does not include webhooks (`plan_upgrade_required`). Webhooks require a paid plan, Starter and above.
- `403`: Missing webhooks.manage or a family read scope.

## Changes

- **2026-10-19** `c34152c38176`: 3 info
  - added the optional property `error/upgrade` to the response with the `400` status
  - added the optional property `error/upgrade` to the response with the `402` status
  - added the optional property `error/upgrade` to the response with the `403` status

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/webhook-endpoints/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)