---
title: "Create a webhook subscription"
method: POST
path: "/webhooks"
tags: ["Webhooks"]
---

# Create a webhook subscription

`POST /webhooks`

Register a destination URL to receive push deliveries for the selected
    events.

    Supported events:
    - `call.ended` — a call finished (status, duration, transcript reference)
    - `call.summary_ready` — the AI summary for a call is available
    - `appointment.booked` — a reservation was confirmed
    - `appointment.updated` — a reservation was rescheduled or its status changed
    - `appointment.cancelled` — a reservation was cancelled
    - `contact.created` — a new contact was created

    The response includes a one-time `secret`. Store it securely: every delivery
    is signed with it via the `X-Webhook-Signature: sha256=<hmac>` header. The
    secret is never retrievable again.

    Authentication:
    - API key with READ_WRITE permission

## Request body

- object — Request body to register a new webhook subscription.
  - `webhook_url` string, required — HTTPS endpoint that will receive event deliveries.
  - `events` string[], required — Event types to subscribe to. Valid values: call.ended, call.summary_ready, call.transcript_ready, appointment.booked, appointment.updated, appointment.cancelled, contact.created, order.created, order.status_changed, dialer.contact.completed, dialer.campaign.completed.
  - `description` string, nullable — Optional human-readable label for this subscription.

## Response `201`

Subscription created

- unknown

## Other responses

- `400` — Invalid request data
- `401` — Invalid or missing API key
- `403` — Insufficient permissions
- `404` — Resource not found

---

[API](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1.md) · [All operations](https://skmtc.net/yourang/apis/yourang-ai-external-api-v1/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yourang/yourang-ai-external-api-v1/versions/49680ee64400/schema)