---
title: "Register a webhook endpoint"
method: POST
path: "/api/webhooks"
tags: ["Webhooks"]
---

# Register a webhook endpoint

`POST /api/webhooks`

## Request

- Base URL: `https://api.wondercal.com`
- URL: `https://api.wondercal.com/api/webhooks`
- Auth: HTTP bearer

Registers a new HTTPS endpoint to receive scheduling events. Requires the Business plan or above. The signing secret is returned once and cannot be retrieved again — store it securely. URLs are validated for HTTPS scheme and checked against private/link-local/loopback/reserved address ranges before the endpoint is created.

## Headers

- `Idempotency-Key` string

## Request body

- CreateWebhookEndpointRequest
  - `url` string, uri, required: Must be https://
  - `subscribedEvents` WebhookEventType[], required: At least one event type is required.

## Response `201`

Webhook endpoint created

- object
  - `data` WebhookEndpointCreated
    - `endpointId` string
    - `url` string, uri
    - `subscribedEvents` WebhookEventType[]
    - `secretKey` string: Plaintext signing secret. Shown once; store securely.
    - `status` 'active'
    - `createdAt` string, date-time

## Other responses

- `400`: Validation error: non-HTTPS URL, empty/unknown event types, blocked address range, or plan-limit cap reached
- `401`: Not authenticated
- `403`: Not authorized (plan gate — unreachable under current policy; all plans include webhooks as of DW-956)
- `409`: Idempotency-Key conflict. Two possible cases: (1) Permanent conflict — the same key was previously used with a different request body. Use a new key for this request. No Retry-After header is present. (2) Transient conflict — a request with the same key is still being processed. The Retry-After header indicates when to retry the identical request.
- `413`: Request body exceeds 1 MB limit
- `429`: Rate limit exceeded. The Retry-After header indicates how many seconds to wait before retrying.

---

[API](https://skmtc.dev/wondercal/apis/wondercal-api.md) · [All operations](https://skmtc.dev/wondercal/apis/wondercal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/wondercal/apis/wondercal-api/revisions/4889176a380f?raw)