Вебхуки та доставка

Після кожного дзвінка Hanc.AI може надіслати його дані — резюме, транскрипт, витягнуті поля — до вашої власної системи: тікет-системи, CRM, ERP або на будь-який HTTPS-ендпоінт. На цій сторінці описано, як саме поводиться ця доставка: що відбувається, коли ваш сервер недоступний, як часто ми повторюємо надсилання, що має пропускати ваш файрвол і який вигляд має запит.

Усі тарифи

Доставка після дзвінка з повторами та журналом доставки доступна на всіх тарифах, включно з Free.

Що надсилається і коли

Запит надсилається, щойно дзвінок завершено і закінчено його аналіз (резюме, тональність, ваші витягнуті поля), — зазвичай за кілька секунд після того, як покладено слухавку.

Джерело	Де налаштовується
Дія «API-виклик»	Агент → Дії → Post call → API-виклик
Крок воркфлоу	Конструктор воркфлоу → крок з інструментом API-виклик і налаштуванням Коли виконується: Після дзвінка
Вебхук агента	Поле `webhook_url` агента (довідник API)

Запити, які агент виконує під час розмови (інструменти живого дзвінка), тут не розглядаються: вони потрібні саме тієї секунди й пізніше ніколи не повторюються.

Коли ваш сервер недоступний

Нічого не втрачається. Запит зберігається в черзі доставки до першої спроби й залишається там, доки ваш сервер його не прийме або доки не вичерпається розклад.

Доставка вважається успішною, якщо ваш ендпоінт відповідає будь-яким статусом 2xx протягом 30 секунд.
Усе інше повторюється: відмова у з'єднанні, помилки DNS або TLS, тайм-аут і будь-який інший статус — 5xx, 429, а також 4xx. Якщо термін дії API-ключа сплив і ви його оновили, дзвінки, що очікують, надійдуть самі.
Кожна спроба надсилає той самий запит із тим самим ID доставки.

Розклад повторів

Спроба	Пауза перед нею	Час від завершення дзвінка
1	— (одразу)	~0
2	1 хвилина	~1 хв
3	5 хвилин	~6 хв
4	30 хвилин	~36 хв
5	2 години	~2 год 36 хв
6	6 годин	~8 год 36 хв
7	24 години	~1 день 8 год
8	48 годин	~3 дні 8 год

Це 8 спроб приблизно за 3,4 дня — достатньо, щоб пережити збій, який припав на вихідні.

Власний розклад

У дії API-виклик (і в кроці воркфлоу API-виклик, який виконується після дзвінка) розклад можна замінити в блоці Повтори при помилці:

до 10 повторів,
кожна пауза — від 1 хвилини до 7 днів,
видаліть усі рядки, щоб запит надсилався один раз, без повторів.

Дія, яку ви жодного разу не змінювали, працює за стандартним розкладом, наведеним вище.

Після останньої спроби

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

Незалежно від вебхуків сам дзвінок залишається у вашому акаунті Hanc.AI — транскрипт, резюме, запис і витягнуті поля доступні в розділі Дзвінки та через API. Тривалий збій затримує передавання до вашої системи, але не видаляє розмову.

Щонайменше один раз

Доставка виконується щонайменше один раз. У рідкісних випадках — наприклад, коли ваш сервер обробив запит, але відповідь не дійшла до нас вчасно, — той самий дзвінок надходить двічі. Використовуйте X-Hanc-Delivery-Id, щоб розпізнати й пропустити повтор.

Сповіщення про збої

Стежити за журналом не обов'язково: дія може повідомити вас електронною поштою, що її запит не доставлено. Виберіть варіант у блоці Сповіщення про збій у дії (або в кроці воркфлоу):

Налаштування	Коли надсилається лист
Після останньої спроби (за замовчуванням)	Один раз, коли розклад повторів вичерпано і запит отримав статус Не доставлено
Після кожної невдалої спроби	Після кожної невдалої спроби, із зазначенням часу наступної, — і після останньої
Не сповіщати	Ніколи; збої видно лише в журналі

У листі вказано дію та агента, хост вашого сервера, його відповідь (наприклад, HTTP 503 або timeout after 30s), номер спроби та їхню загальну кількість, а також є посилання на журнал доставки. В останньому листі додатково вказано, до якого часу зберігається запит, і зазначено, що його можна надіслати знову.

Поле Куди писати задає отримувача — зазвичай це той, хто відповідає за систему, яка приймає запити. Якщо залишити його порожнім, лист надійде власникові акаунта. Лист складається мовою акаунта.

Щоб збій не переповнив вашу поштову скриньку, сповіщення обмежено для кожної дії: 10 на годину і 30 на добу; в останньому листі перед паузою вказано, до якого часу вона триватиме. Кожен збій, як і раніше, записується в журнал. Про запит, який ви надіслали знову вручну, сповіщення не надходять.

Журнал доставки

Записується кожна спроба: час, HTTP-статус або мережева помилка, тривалість і початок відповіді вашого сервера.

У застосунку: CRM → Комунікації → відкрийте запис типу API-виклик. Ви побачите статус (Доставлено, Повторюється, Не доставлено), усі спроби, час наступної та кнопку Надіслати знову.

Через API (автентифікація вашим API-ключем у заголовку x-api-key):

Запит	Результат
`GET /v1/webhook-deliveries`	Ваші доставки, спочатку найновіші. Фільтри: `status` (`pending`, `delivered`, `failed`), `agent_id`, `call_id`, `limit`, `offset`
`GET /v1/webhook-deliveries/{id}`	Одна доставка з усіма спробами та тілом запиту
`POST /v1/webhook-deliveries/{id}/resend`	Надсилає її знову просто зараз і повертає результат

{
  "id": "6ac71fb82e4f72e709a4a566",
  "delivery_id": "0b0f2f0e-6c0f-4f0b-9c55-3c6a3a1f8a11",
  "kind": "api_call",
  "name": "Create ticket",
  "call_id": "6ac71f9d2e4f72e709a4a4f0",
  "status": "pending",
  "attempts_made": 2,
  "attempts_max": 8,
  "next_attempt_at": "2026-10-09T11:36:04.000Z",
  "attempts": [
    { "n": 1, "at": "2026-10-09T11:30:03.512Z", "duration_ms": 212, "error": "connection refused" },
    { "n": 2, "at": "2026-10-09T11:31:04.007Z", "duration_ms": 187, "status_code": 503, "error": "HTTP 503", "response_preview": "Service Unavailable" }
  ]
}

Значення заголовків збереженого запиту (ваші ключі) ніколи не повертаються.

Мережа та файрвол

Hanc.AI звертається до вашого ендпоінта — з'єднання завжди встановлюється з нашого боку до вашого.


Напрямок	Вихідне з боку Hanc.AI → вхідне на вашому боці
IP-адреси джерела	`178.104.10.47` (сервіс доставки) і `128.140.65.92` (сервіс дзвінків, використовується як резервний шлях)
Протокол	HTTPS (TLS 1.2 або новіший). Звичайний HTTP працює, але не рекомендується
Порт	`443` або той порт, який указано у вашому URL
Версія IP	IPv4
Сертифікат	Має бути чинним і виданим публічним центром сертифікації; самопідписані сертифікати відхиляються
Час відповіді	Відповідь протягом 30 секунд — найкраще одразу підтвердити приймання, а обробку виконати у фоні
Перенаправлення	Виконуються, не більше 5

Список дозволених адрес: якщо ваш файрвол або WAF фільтрує за адресою джерела, дозвольте дві зазначені вище адреси для шляху вашого вебхука. Про зміну цих адрес ми повідомляємо заздалегідь.

Неможливо: адреси всередині приватної мережі (10.x, 172.16–31.x, 192.168.x, localhost). Ендпоінт має бути доступним з інтернету — безпосередньо або через ваш зворотний проксі чи API-шлюз.

Браузер: вебхуки передаються із сервера на сервер. Налаштування браузера, розширення та відкриті порти на робочих комп'ютерах працівників не задіяні.

Формат запиту

Запити POST, PUT і PATCH містять тіло у форматі JSON (Content-Type: application/json, UTF-8).

{
  "call_from": "+431234567890",
  "call_to":   "+439876543210",
  "direction": "inbound",
  "call_type": "phone",
  "call_status": "ended",
  "start_timestamp": 1730000000000,
  "end_timestamp":   1730000187000,
  "duration": 187000,
  "call_summary": "Customer reports a broken router and asks for a callback…",
  "transcription": [
    { "speaker": "agent", "content": "Hello…", "timestamp": 1730000001000 },
    { "speaker": "user",  "content": "Hi…",    "timestamp": 1730000003000 }
  ],
  "task_achieved": true,
  "sentiment": { "sentiment": "neutral", "explanation": "…" },
  "custom_analysis_data": {
    "customer_number": "K-20417",
    "ticket_category": "Hardware",
    "priority": "high"
  },
  "collected_data": { },
  "transfer_history": [ ],
  "recording_url": "https://…",
  "disconnection_reason": "user_hangup"
}

Поле	Вміст
`call_summary`	Резюме розмови
`transcription`	Повна розмова, репліка за реплікою, з часовими мітками
`call_from`, `call_to`, `direction`	Номер абонента, який телефонує, номер, на який телефонують, напрямок — вхідний або вихідний
`start_timestamp`, `end_timestamp`, `duration`	Час у форматі Unix і тривалість у мілісекундах
`custom_analysis_data`	Ваші власні поля, витягнуті з розмови, — див. Змінні для збору (Retrieval Variables)
`collected_data`	Дані, які агент зібрав під час дзвінка
`sentiment`, `task_achieved`	Тональність розмови і чи досягнуто її мети
`recording_url`	Посилання на запис, якщо запис увімкнено
`transfer_history`	Переведення, які відбулися під час дзвінка

Для GET і DELETE ті самі поля передаються в рядку запиту; вкладені значення, як-от transcription, пропускаються.

Заголовки

Заголовок	Призначення
`X-Hanc-Delivery-Id`	Ідентифікує доставку. Однаковий за кожної спроби — використовуйте його, щоб пропускати дублікати
`X-Hanc-Attempt`	Номер спроби, починаючи з `1`
`X-Correlation-Id`	Внутрішній ID трасування; зазначте його, звертаючись до підтримки
`User-Agent`	`HANC-Webhooks/1.0`
ваші заголовки	Усе, що ви налаштували в дії

Автентифікація

Ви самі вирішуєте, як ваш ендпоінт нас розпізнає:

API-ключ або токен — додайте до дії заголовок, наприклад Authorization: Bearer <token> або X-API-Key: <key>. Заголовки надсилаються з кожною спробою.
Basic-автентифікація — Authorization: Basic <base64(user:password)>.
Параметр запиту — для систем, які очікують ключ в URL.
Адреса джерела — дозвольте лише перелічені вище IP-адреси.

Способи можна поєднувати; звичайна схема — ключ плюс список дозволених IP-адрес.

Формування запиту під вашу систему

За замовчуванням запит містить усі дані дзвінка (див. Формат запиту). Для системи, яка очікує власну структуру (а таких тікет-систем більшість), ви самі описуєте цю структуру й заповнюєте її даними дзвінка.

Змінні

У дії API-виклик після дзвінка та в кроці воркфлоу API-виклик поля URL, заголовки, параметри запиту і тіло приймають змінні в подвійних фігурних дужках. Вони заповнюються даними дзвінка безпосередньо перед надсиланням запиту.

Змінна	Значення
`{{call_id}}`	ID дзвінка
`{{call_from}}`, `{{call_to}}`	Номер абонента, який телефонує, і номер, на який телефонують
`{{customer_phone}}`, `{{customer_email}}`	Номер і адреса електронної пошти співрозмовника — за будь-якого напрямку дзвінка
`{{call_direction}}`, `{{call_type}}`	`inbound` / `outbound`, `phone` / `web`
`{{call_start}}`, `{{call_end}}`	Початок і кінець, ISO 8601 (UTC)
`{{call_duration}}`	Тривалість у секундах
`{{call_summary}}`	Резюме розмови
`{{call_transcription}}`	Повна розмова у вигляді тексту
`{{call_sentiment}}`, `{{call_task_achieved}}`	Тональність і чи досягнуто мети
`{{call_recording_url}}`	Посилання на запис
`{{agent_id}}`	ID агента
ваші поля	Кожна змінна для збору за її назвою, наприклад `{{customer_number}}`, `{{priority}}`, — а також кожна змінна, яку воркфлоу зібрав під час дзвінка

Правила, які варто знати:

Поле тіла, що складається лише з однієї змінної, зберігає тип цієї змінної: "priority": "{{priority}}" надсилається як число 3, "urgent": "{{urgent}}" — як true. Якщо поруч зі змінною є текст, значення стає текстом.
Значення, підставлене в URL, автоматично проходить URL-кодування (+43… перетворюється на %2B43…).
Змінна, для якої у дзвінку немає значення, надсилається порожньою — і ніколи не йде буквальним рядком {{name}}.

У застосунку кнопка {x} у полі відкриває список доступних змінних; у тілі запиту вони пропонуються під час введення {{.

Тіло запиту

У полі Тіло (JSON) у дії ви пишете JSON-об'єкт, якого очікує ваша система, з будь-якою потрібною глибиною вкладеності:

{
  "ticket": {
    "subject": "Call from {{customer_phone}}: {{ticket_category}}",
    "comment": { "body": "{{call_summary}}" },
    "priority": "{{priority}}",
    "custom_fields": [
      { "id": 360001, "value": "{{customer_number}}" },
      { "id": 360002, "value": "{{call_recording_url}}" }
    ],
    "tags": ["phone-agent"]
  }
}

Лише ваші поля

Якщо ввімкнено перемикач Надсилати лише мої поля, запит містить лише ваше тіло та ваші параметри запиту — дані дзвінка не додаються. Якщо залишити його вимкненим, ваші поля надсилаються разом із повними даними дзвінка.

Вибіркове надсилання

Умова, записана звичайними словами («лише якщо абонент повідомляє про несправність»), визначає, які дзвінки запускають запит. Кілька дій можуть вести до різних систем або на різні ендпоінти.

Підключення тікет-системи

Будь-яка тікет-система з HTTP API або вхідним вебхуком може приймати дзвінки — безпосередньо, без проміжного програмного забезпечення. Що потрібно з вашого боку:

Ендпоінт, доступний з інтернету через HTTPS, який приймає JSON.
Облікові дані для нього (API-ключ, токен або Basic-автентифікація), зазначені в дії у вигляді заголовка.
Якщо ви фільтруєте за адресою — дві IP-адреси, наведені вище, у вашому списку дозволених.

Далі в дії:

Визначте свої поля. Додайте змінні для збору, наприклад номер клієнта, категорія заявки, пріоритет, потрібен зворотний дзвінок. Агент заповнює їх на основі розмови.
Напишіть тіло у структурі API вашої тікет-системи й розставте змінні на потрібні місця.
Увімкніть Надсилати лише мої поля.
Натисніть Перевірити конфігурацію API, потім зробіть тестовий дзвінок.

Ми охоче підготуємо тіло запиту для вашої системи разом із вами.

Тестування

Перевірка з'єднання. Кнопка Перевірити конфігурацію API в дії одразу надсилає пробний запит і показує, чи вдалося зв'язатися з вашим ендпоінтом.

Перевірка повторів — щоб побачити механізм на власні очі:

У дії задайте короткий розклад у блоці Повтори при помилці, наприклад три паузи по 1 хвилині.
Зупиніть свій ендпоінт або заблокуйте наші адреси у файрволі.
Зробіть тестовий дзвінок агентові.
Відкрийте CRM → Комунікації: у записі відображаються статус Повторюється, невдала спроба з її помилкою та час наступної.
Знову запустіть ендпоінт (або зніміть блокування). Наступна спроба доставить дзвінок, і запис перейде в статус Доставлено — або натисніть Надіслати знову, щоб доставити негайно.

Контрольний список для вашого ендпоінта

Відповідайте 2xx, щойно запит збережено; ресурсомістку обробку виконуйте після цього.
Використовуйте X-Hanc-Delivery-Id як ключ ідемпотентності.
Відповідайте 4xx/5xx, якщо ви не змогли прийняти запит, — ми звернемося знову.
Стежте, щоб сертифікат залишався чинним, а дві адреси джерела — дозволеними.

Що надсилається і коли​

Коли ваш сервер недоступний​

Розклад повторів​

Власний розклад​

Після останньої спроби​

Сповіщення про збої​

Журнал доставки​

Мережа та файрвол​

Формат запиту​

Заголовки​

Автентифікація​

Формування запиту під вашу систему​

Змінні​

Тіло запиту​

Лише ваші поля​

Вибіркове надсилання​

Підключення тікет-системи​

Тестування​

Контрольний список для вашого ендпоінта​