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

# Create a webhook endpoint

`POST /webhook-endpoints`

## Request

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

Add an endpoint. The response includes its signing `secret`: store it now, it is not shown again.

Creating an endpoint for a URL the account already has is safe to retry: instead of a duplicate, you get
that endpoint back (status 200) with the new events added, switched on, and its existing secret.

## Request body

- StoreWebhookEndpointRequest
  - `url` string, uri, required: A public HTTPS URL.
  - `events` WebhookEvent[], required: The events to send, at least one. The key needs the read scope of each event's record: `lead.created` needs `leads:read`, `call.completed`, `call.missed` and `message.taken` need `calls:read`, `booking.created` needs `bookings:read`, `outbound_call.completed` needs `outbound:read` (or `outbound:write`), every `chat.*` event needs `chats:read`, and `chat.lead_captured` also needs `leads:read`.
  - `description` string, nullable

## Response `200`

The account already had an endpoint for this URL: that endpoint, with the events added, and its secret.

- object
  - `data` WebhookEndpointResource, required
    - `id` integer, required
    - `livemode` boolean, required: `true` for live data, `false` for test data (created with a `vk_test_` key).
    - `url` string, required
    - `description` string, nullable, required
    - `events` WebhookEvent[], required: The events sent to this endpoint.
    - `enabled` boolean, required
    - `created_at` string, nullable, required
  - `secret` string, required

## Other responses

- `201`: The endpoint and its signing secret.
- `401`: The API key is missing, invalid, expired or revoked.
- `403`: The key lacks the read scope of a subscribed event, for example `leads:read` for `lead.created` (`missing_scope`).
- `422`: Validation failed, the URL is not a public HTTPS address (`unsafe_url`), or the account already has 50 endpoints (`too_many_endpoints`).
- `429`: Too many requests for this key. Wait for the `Retry-After` seconds.

---

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