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

Керуйте кількома URL-адресами вебхуків із секретами для кожної кінцевої точки та фільтрами подій.

Система вебхуків на основі ендпоінтів дає змогу зареєструвати кілька призначень для кожної організації, кожне з власним секретом, власним статусом і власною підпискою на підмножину типів подій. Це рекомендована модель для всіх нових інтеграцій.

Порівняйте із застарілим вебхуком з однією URL-адресою, який збережено для зворотної сумісності, але він підтримує лише одну URL-адресу на організацію.

Ендпоінти#

Об’єкт endpoint#

{
  "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"
}

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

Значення events перевіряється за цим точним набором — значення поза списком повертають 400. Див. каталог подій, щоб переглянути структуру 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#

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

Повертає масив об’єктів endpoint. Передайте ?agent_id=42, щоб повернути лише endpoint, прив’язані до цього агента.

Endpoint, прив’язані до агента#

Endpoint рівня організації отримують кожну відповідну подію. Endpoint з agent_id отримує лише відповідні події для дзвінків, які обробляє цей агент; події без контексту агента, наприклад alert.triggered, ніколи не надходять до нього. Ви також можете створювати ці endpoint і керувати ними в конструкторі агента, у розділі Вебхуки.

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

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

Поля запиту#

Повертає 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"
}

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

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

Повертає 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 кінцевої точки. Якщо перша спроба не вдасться, ThunderPhone повторить її один раз приблизно через хвилину, а потім зупиниться; після цього доставка матиме status: "failed" у розділі Налагодження доставок. Тестова доставка ніколи не позначає кінцеву точку як failing.

Щоб налаштувати тригер для реальної структури події, передайте необов’язковий event_type. Доставка все одно є синтетичною та містить "sample": true; зразки, пов’язані з дзвінками, використовують call_id: 0 і agent_id: 0.

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

Видалити кінцеву точку#

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

Ту саму нещодавню історію також можна переглянути в Агенти → виберіть агента → Вебхуки → Останні доставки. Рядки показують мітку кінцевої точки та походження URL, використане в останній спробі. Це операційний стан, а не незмінний журнал аудиту: видалення кінцевої точки також видаляє її рядки доставок.

Для 404 від n8n спочатку переконайтеся, що робочий процес активний, приймає POST і використовує URL вебхука для продакшну, а не тестовий URL. 401 або 403 вказує на автентифікацію чи перевірку підпису; тайм-аути вказують на затримку або недоступність цільового призначення; помилки TLS — на ланцюжок сертифікатів, ім’я хоста або строк дії.

Пов’язані матеріали#