---
title: "Кінцеві точки вебхуків"
description: "Керуйте кількома 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+` | Надіслати підписану тестову доставку |
| `GET` | `/v1/developer/webhook-deliveries` | `admin+` | Переглянути останні результати доставок ендпоінтів і застарілих вебхуків |
## Об’єкт endpoint
```json
{
"id": "c4d5e6f7-...",
"label": "Production — Call events",
"url": "https://example.com/thunderphone/hook",
"events": ["telephony.incoming", "telephony.complete"],
"status": "active",
"agent_id": 42,
"agent_name": "Support Agent",
"secret_hint": "a1b2…9f0e",
"created_at": "2026-04-20T18:24:10.113Z",
"updated_at": "2026-04-20T18:24:10.113Z"
}
```
| Поле | Тип | Опис |
|-------|------|-------------|
| `id` | UUID | ID endpoint |
| `label` | string | Відображувана назва, 1–120 символів |
| `url` | string | HTTPS URL; для розробки дозволено `http://localhost` |
| `events` | масив string | Типи подій, на які оформлено підписку (див. [допустимі значення](#valid-event-types)). Порожній масив підписує на всі події, крім явних подій кожного ходу (`telephony.turn` / `web.turn`) |
| `status` | string | `active`, `disabled` (призупинено вручну) або `failing` (встановлюється автоматично, коли доставляння вичерпує свій 24-годинний графік повторних спроб без жодної відповіді 2xx) |
| `agent_id` | integer \| null | Агент, до якого прив’язано цей endpoint; `null` означає рівень організації |
| `agent_name` | string \| null | Ім’я агента, до якого прив’язано endpoint, або `null` для endpoint рівня організації |
| `secret_hint` | string | Перші 4 та останні 4 символи секрету підпису з трикрапкою (`a1b2…9f0e`) — достатньо, щоб зіставити його із секретом, який ви зберегли локально, не розкриваючи повне значення |
| `created_at`, `updated_at` | timestamp | |
Повний `secret` endpoint повертається **лише один раз** під час створення
і більше ніколи. Зберігайте його безпечно — якщо ви його втратите, видаліть endpoint
і створіть його повторно.
### Допустимі типи подій
Значення `events` перевіряється за цим точним набором — значення поза списком
повертають `400`. Див. [каталог подій](/uk/webhooks/events), щоб переглянути
структуру payload для кожного типу.
- `telephony.incoming`, `telephony.complete`, `telephony.tool`, `telephony.turn`
- `web.incoming`, `web.complete`, `web.tool`, `web.turn`
- `sms.sent`, `sms.failed`
- `sms.received` (зарезервовано; ще не надсилається)
- `call.graded`, `call.data_extracted`
- `campaign.completed`
- `issue.reported`, `issue.escalated`
- `test-call.completed`
- `alert.triggered`
`issue.escalated` не має контексту агента та доставляється лише до
endpoint рівня організації.
`voice.ready` і `voice.failed` не можна вибрати явно. Щоб отримувати
їх, створіть endpoint рівня організації з `events: []`. Порожній список подій
отримує кожну підтримувану подію, крім `telephony.turn` і `web.turn`,
які потрібно вибрати явно.
### Статуси endpoint
- `active` — доставляння відбувається як зазвичай.
- `disabled` — призупинено вручну через `PATCH`. Запити не надсилаються. Ми
ніколи не змінюємо статус endpoint зі статусом `disabled`; повернути його до
`active` — завжди ваше рішення.
- `failing` — встановлюється автоматично, коли доставляння до endpoint вичерпує
весь графік повторних спроб (8 спроб протягом 24 годин), жодного разу
не отримавши 2xx. Endpoint зі статусом failing не отримує подальшого трафіку.
Щойно endpoint буде виправлено, змініть його статус через `PATCH` назад на `active`;
доставляння, чий графік повторних спроб ще не завершився, продовжаться з місця,
на якому зупинилися.
---
## Список endpoint
```bash cURL
curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Повертає масив [об’єктів endpoint](#endpoint-object).
Передайте `?agent_id=42`, щоб повернути лише endpoint, прив’язані до цього агента.
### Endpoint, прив’язані до агента
Endpoint рівня організації отримують кожну відповідну подію. Endpoint з
`agent_id` отримує лише відповідні події для дзвінків, які обробляє цей агент;
події без контексту агента, наприклад `alert.triggered`, ніколи не надходять до нього. Ви
також можете створювати ці endpoint і керувати ними в конструкторі агента,
у розділі **Вебхуки**.
---
## Створення кінцевої точки
```bash cURL
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
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` | масив | ні | Порожнє або пропущене значення підписує на всі події, окрім `telephony.turn` / `web.turn`, для яких потрібна явна підписка. Потрібно використовувати значення, наведені в розділі [Дійсні типи подій](#valid-event-types); дублікати видаляються |
| `agent_id` | ціле число \| null | ні | Обмежує доставку агентом у цій організації; пропустіть або використайте `null` для кінцевої точки рівня організації |
Повертає `201 Created` з [об’єктом кінцевої точки](#endpoint-object) і додатковим полем верхнього рівня `secret`, що містить необроблений ключ підпису — 48-символьний шістнадцятковий рядок:
```json
{
"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
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` |
| `agent_id` | ціле число \| null | Установіть ідентифікатор агента, щоб обмежити кінцеву точку, або `null`, щоб зробити її загальною для організації |
Повертає `200 OK` з оновленим [об’єктом кінцевої точки](#endpoint-object).
---
## Надіслати тестову доставку
Надішліть синтетичну подію `webhook.test` до однієї кінцевої точки через звичайний
конвеєр доставки, включно з канонічною серіалізацією JSON,
`X-ThunderPhone-Signature`, записом доставки та обліком повторних спроб.
Тест спрямовується на вибрану кінцеву точку незалежно від її фільтра `events`.
```bash cURL
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Кінцева точка отримує оболонку такого вигляду:
```json
{
"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
{
"success": true,
"event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
"event_type": "webhook.test",
"status": "delivered",
"response_code": 204,
"error": ""
}
```
`webhook.test` є синтетичною подією та не може бути додана до підписки `events`
кінцевої точки. Якщо перша спроба не вдасться, ThunderPhone повторить її один раз приблизно
через хвилину, а потім зупиниться; після цього доставка матиме `status: "failed"`
у розділі [Налагодження доставок](#debug-deliveries). Тестова доставка ніколи не позначає
кінцеву точку як `failing`.
Щоб налаштувати тригер для реальної структури події, передайте необов’язковий
`event_type`. Доставка все одно є синтетичною та містить `"sample": true`;
зразки, пов’язані з дзвінками, використовують `call_id: 0` і `agent_id: 0`.
```bash
curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{"event_type":"call.graded"}'
```
`event_type` приймає будь-яке значення з [Допустимих типів подій](#valid-event-types).
Якщо його не вказати, зберігається загальна поведінка `webhook.test`.
---
## Видалити кінцеву точку
```bash cURL
curl -X DELETE https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-... \
-H "Authorization: Bearer sk_live_YOUR_API_KEY"
```
Повертає `204 No Content`. Доставка на URL негайно припиняється;
повторні спроби, що виконуються, скасовуються.
---
## Налагодження доставок
Перш ніж робити висновок, що вебхук не було надіслано, перевірте
[`GET /v1/developer/webhook-deliveries`](/api-reference/webhook-deliveries).
Він показує останні спроби з обох систем вебхуків, включно з ідентифікатором дзвінка,
походженням URL, статусом HTTP, кількістю спроб, категорією помилки з дозволеного списку та часом
наступної повторної спроби. Він ніколи не повертає корисне навантаження події, транскрипт, збережений текст помилки,
тіло відповіді або шлях URL.
Ту саму нещодавню історію також можна переглянути в **Агенти → виберіть агента → Вебхуки →
Останні доставки**. Рядки показують мітку кінцевої точки та походження URL, використане в останній
спробі. Це операційний стан, а не незмінний журнал аудиту: видалення кінцевої точки
також видаляє її рядки доставок.
Для `404` від n8n спочатку переконайтеся, що робочий процес активний, приймає `POST` і використовує
URL вебхука для продакшну, а не тестовий URL. `401` або `403` вказує на
автентифікацію чи перевірку підпису; тайм-аути вказують на затримку
або недоступність цільового призначення; помилки TLS — на ланцюжок сертифікатів, ім’я хоста або строк дії.
---
## Пов’язані матеріали
Повний список значень `events`, на які можна підписатися.
Перевірка підпису та семантика доставки.