> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Кінцеві точки вебхуків
> Керуйте кількома URL-адресами вебхуків із секретами для кожної кінцевої точки та фільтрами подій.
Система вебхуків на основі кінцевих точок дає змогу реєструвати **кілька**
адрес призначення для кожної організації, кожну з власним секретом, власним
статусом і власною підпискою на підмножину типів подій. Це рекомендована
модель для всіх нових інтеграцій.
Порівняйте з [застарілим вебхуком з єдиною URL-адресою](/api-reference/organizations#legacy-single-url-webhook),
який зберігається для зворотної сумісності, але підтримує лише одну URL-адресу
на організацію.
## Кінцеві точки
| Метод | Шлях | Необхідна роль | Опис |
| -------- | ---------------------------------------------------- | -------------- | ------------------------------------------- |
| `GET` | `/v1/developer/webhook-endpoints` | `admin+` | Отримати список кінцевих точок |
| `POST` | `/v1/developer/webhook-endpoints` | `admin+` | Створити кінцеву точку |
| `PATCH` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Оновити мітку / URL-адресу / події / статус |
| `DELETE` | `/v1/developer/webhook-endpoints/{endpoint_id}` | `admin+` | Видалити кінцеву точку |
| `POST` | `/v1/developer/webhook-endpoints/{endpoint_id}/test` | `admin+` | Надіслати підписану тестову доставку |
## Об’єкт кінцевої точки
```json theme={null}
{
"id": "c4d5e6f7-...",
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
"status": "active",
"secret_hint": "a1b2…9f0e",
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z"
}
```
| Поле | Тип | Опис |
| -------------------------- | ------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id` | UUID | Ідентифікатор кінцевої точки |
| `label` | string | Відображувана назва, 1–120 символів |
| `url` | string | HTTPS URL-адреса; для розробки дозволено `http://localhost` |
| `events` | масив рядків | Типи подій, на які оформлено підписку (див. [допустимі значення](#valid-event-types)). Порожній масив підписує на всі події |
| `status` | string | `active`, `disabled` (призупинено вручну) або `failing` (встановлюється автоматично, коли доставка вичерпує 24-годинний графік повторних спроб без жодної відповіді 2xx) |
| `secret_hint` | string | Перші 4 й останні 4 символи секрету підписування з трикрапкою (`a1b2…9f0e`) — достатньо, щоб зіставити із секретом, який ви зберегли локально, не розкриваючи повне значення |
| `created_at`, `updated_at` | timestamp | |
Повний `secret` кінцевої точки повертається **лише один раз** під час створення
і більше ніколи. Зберігайте його безпечно — якщо ви його втратите, видаліть
кінцеву точку та створіть її повторно.
### Допустимі типи подій
`events` перевіряється за цим точним набором — значення поза списком
повертають `400`. Перегляньте [каталог подій](/uk/webhooks/events), щоб дізнатися
структуру корисного навантаження кожного типу.
* `telephony.incoming`, `telephony.complete`, `telephony.tool`
* `web.incoming`, `web.complete`, `web.tool`
* `call.graded`
* `issue.reported`
* `test-call.completed`
* `alert.triggered`
### Статуси кінцевих точок
* `active` — доставки виконуються у звичайному режимі.
* `disabled` — призупинено вручну через `PATCH`. Запити не надсилаються. Ми
ніколи не змінюємо статус кінцевої точки `disabled`; повернути її до
`active` — завжди ваше рішення.
* `failing` — встановлюється автоматично, коли доставка до кінцевої точки
вичерпує весь графік повторних спроб (8 спроб протягом 24 годин), так і не
отримавши відповідь 2xx. Кінцева точка зі статусом помилки не отримує
подальшого трафіку. Після виправлення кінцевої точки через `PATCH` змініть її
статус назад на `active`; доставки, чий графік повторних спроб ще не
вичерпано, відновляться з того місця, де зупинилися.
***
## Отримати список кінцевих точок
```bash cURL theme={null}
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Повертає масив [об’єктів кінцевих точок](#endpoint-object).
***
## Створення кінцевої точки
```bash cURL theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"]
}'
```
```python Python theme={null}
result = requests.post(
"https://api.thunderphone.com/v1/developer/webhook-endpoints",
headers={"Authorization": "Bearer sk_live_YOUR_API_KEY"},
json={
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
},
).json()
secret = result["secret"]
endpoint_id = result["id"]
```
### Поля запиту
| Поле | Тип | Обов’язкове | Опис |
| -------- | ----- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `label` | рядок | так | 1–120 символів |
| `url` | рядок | так | HTTPS URL (`http` дозволено лише для `localhost` / `127.0.0.1`) |
| `events` | масив | ні | Порожнє або пропущене значення підписує на всі події. Потрібно використовувати значення, перелічені в [Допустимі типи подій](#valid-event-types); дублікати видаляються |
Повертає `201 Created` з [об’єктом кінцевої точки](#endpoint-object) і додатковим полем верхнього рівня `secret`, яке містить необроблений ключ підпису — 48-символьний шістнадцятковий рядок:
```json theme={null}
{
"id": "c4d5e6f7-…",
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
"status": "active",
"secret_hint": "a1b2…9f0e",
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z",
"secret": "a1b2c37e08d94f5b16a2c8d90e7f3a4b5c6d7e8f90a19f0e"
}
```
`secret` повертається **лише під час створення**. Наступні відповіді `GET`
містять лише `secret_hint`. Скопіюйте повне значення до свого менеджера
секретів, перш ніж закрити відповідь.
***
## Оновлення кінцевої точки
```bash cURL theme={null}
curl -X PATCH https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Production — Call + Grade events",
"events": ["telephony.incoming", "telephony.complete", "call.graded"]
}'
```
| Поле | Тип | Опис |
| -------- | ----- | -------------------------------------------------------------------------------------------------------------------- |
| `label` | рядок | |
| `url` | рядок | |
| `events` | масив | |
| `status` | рядок | `active` або `disabled`. Установіть `active`, щоб повторно ввімкнути кінцеву точку, яку сервер позначив як `failing` |
Повертає `200 OK` з оновленим [об’єктом кінцевої точки](#endpoint-object).
***
## Надсилання тестової доставки
Надішліть синтетичну подію `webhook.test` до однієї кінцевої точки через звичайний конвеєр доставки, включно з канонічною серіалізацією JSON, `X-ThunderPhone-Signature`, записом доставки та обліком повторних спроб.
Тест спрямовується до вибраної кінцевої точки незалежно від її фільтра `events`.
```bash cURL theme={null}
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Кінцева точка отримує конверт такого вигляду:
```json theme={null}
{
"data": {
"message": "ThunderPhone webhook test",
"sent_at": "2026-07-17T20:12:34.567890+00:00"
},
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"type": "webhook.test"
}
```
API повертає `200 OK` після першої спроби, навіть якщо призначення повертає помилку. Перевірте `success`, `status`, `response_code` та `error`, щоб дізнатися результат доставки:
```json theme={null}
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` є синтетичною подією, і її не можна додати до підписки `events` кінцевої точки. Якщо перша спроба не вдається, доставка виконується за таким самим графіком повторних спроб, як і звичайні доставки подій.
***
## Видалення ендпоінта
```bash cURL theme={null}
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Повертає `204 No Content`. Доставка на URL негайно припиняється;
повторні спроби, що виконуються, скасовуються.
***
## Пов’язані матеріали
Повний список значень `events`, на які можна підписатися.
Перевірка підпису та семантика доставки.