Кінцеві точки вебхуків

Система вебхуків на основі кінцевих точок дає змогу реєструвати кілька адрес призначення для кожної організації, кожну з власним секретом, власним статусом і власною підпискою на підмножину типів подій. Це рекомендована модель для всіх нових інтеграцій. Порівняйте з застарілим вебхуком з єдиною URL-адресою, який зберігається для зворотної сумісності, але підтримує лише одну 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+`	Надіслати підписану тестову доставку

Об’єкт кінцевої точки

{
  "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`	масив рядків	Типи подій, на які оформлено підписку (див. допустимі значення). Порожній масив підписує на всі події
`status`	string	`active`, `disabled` (призупинено вручну) або `failing` (встановлюється автоматично, коли доставка вичерпує 24-годинний графік повторних спроб без жодної відповіді 2xx)
`secret_hint`	string	Перші 4 й останні 4 символи секрету підписування з трикрапкою (`a1b2…9f0e`) — достатньо, щоб зіставити із секретом, який ви зберегли локально, не розкриваючи повне значення
`created_at`, `updated_at`	timestamp

Повний secret кінцевої точки повертається лише один раз під час створення і більше ніколи. Зберігайте його безпечно — якщо ви його втратите, видаліть кінцеву точку та створіть її повторно.

Допустимі типи подій

events перевіряється за цим точним набором — значення поза списком повертають 400. Перегляньте каталог подій, щоб дізнатися структуру корисного навантаження кожного типу.

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; доставки, чий графік повторних спроб ще не вичерпано, відновляться з того місця, де зупинилися.

Отримати список кінцевих точок

curl https://api.thunderphone.com/v1/developer/webhook-endpoints \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Повертає масив об’єктів кінцевих точок.

Створення кінцевої точки

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"]
  }'

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`	масив	ні	Порожнє або пропущене значення підписує на всі події. Потрібно використовувати значення, перелічені в Допустимі типи подій; дублікати видаляються

Повертає 201 Created з об’єктом кінцевої точки і додатковим полем верхнього рівня secret, яке містить необроблений ключ підпису — 48-символьний шістнадцятковий рядок:

{
  "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. Скопіюйте повне значення до свого менеджера секретів, перш ніж закрити відповідь.

Оновлення кінцевої точки

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 з оновленим об’єктом кінцевої точки.

Надсилання тестової доставки

Надішліть синтетичну подію webhook.test до однієї кінцевої точки через звичайний конвеєр доставки, включно з канонічною серіалізацією JSON, X-ThunderPhone-Signature, записом доставки та обліком повторних спроб. Тест спрямовується до вибраної кінцевої точки незалежно від її фільтра events.

curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints/c4d5e6f7-.../test \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY"

Кінцева точка отримує конверт такого вигляду:

{
  "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, щоб дізнатися результат доставки:

{
  "success": true,
  "event_id": "2ad6507c-7d19-4498-9b2d-7e8f944ab5a1",
  "event_type": "webhook.test",
  "status": "delivered",
  "response_code": 204,
  "error": ""
}

webhook.test є синтетичною подією, і її не можна додати до підписки events кінцевої точки. Якщо перша спроба не вдається, доставка виконується за таким самим графіком повторних спроб, як і звичайні доставки подій.

Видалення ендпоінта

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, на які можна підписатися.

Огляд вебхуків

Перевірка підпису та семантика доставки.

Webhooks

Function Tools

Кінцеві точки вебхуків