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

После каждого звонка 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)>.
Query-параметр — для систем, которые ожидают ключ в URL.
Адрес источника — разрешите только перечисленные выше IP-адреса.

Способы можно комбинировать; обычная схема — ключ плюс список разрешённых IP-адресов.

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

По умолчанию запрос содержит все данные звонка (см. Формат запроса). Для системы, которая ожидает собственную структуру (а таких тикет-систем большинство), вы сами описываете эту структуру и заполняете её данными звонка.

Переменные

В действии API-вызов после звонка и в шаге воркфлоу API-запрос поля URL, заголовки, query-параметры и тело принимают переменные в двойных фигурных скобках. Они заполняются данными звонка непосредственно перед отправкой запроса.

Переменная	Значение
`{{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"]
  }
}

Только ваши поля

Если включён переключатель Отправлять только мои поля, запрос содержит только ваше тело и ваши query-параметры — данные звонка не добавляются. Если оставить его выключенным, ваши поля отправляются вместе с полными данными звонка.

Выборочная отправка

Условие, записанное обычными словами («только если звонящий сообщает о неисправности»), определяет, какие звонки запускают запрос. Несколько действий могут вести в разные системы или на разные эндпоинты.

Подключение тикет-системы

Любая тикет-система с HTTP API или входящим вебхуком может принимать звонки — напрямую, без промежуточного программного обеспечения. Что требуется с вашей стороны:

Эндпоинт, доступный из интернета по HTTPS и принимающий JSON.
Учётные данные для него (API-ключ, токен или Basic-аутентификация), указанные в действии в виде заголовка.
Если вы фильтруете по адресу — два IP-адреса, приведённых выше, в вашем списке разрешённых.

Затем в действии:

Определите свои поля. Добавьте переменные извлечения, например номер клиента, категория заявки, приоритет, нужен обратный звонок. Агент заполняет их на основе разговора.
Напишите тело в структуре API вашей тикет-системы и расставьте переменные по нужным местам.
Включите Отправлять только мои поля.
Нажмите Проверить настройку API, затем сделайте тестовый звонок.

Мы с удовольствием подготовим тело запроса для вашей системы вместе с вами.

Тестирование

Проверка соединения. Кнопка Проверить настройку API в действии сразу отправляет пробный запрос и показывает, удалось ли связаться с вашим эндпоинтом.

Проверка повторов — чтобы увидеть механизм своими глазами:

В действии задайте короткое расписание в блоке Повторы при ошибке, например три паузы по 1 минуте.
Остановите свой эндпоинт или заблокируйте наши адреса в файрволе.
Сделайте тестовый звонок агенту.
Откройте CRM → Коммуникации: в записи отображаются статус Повторяется, неудачная попытка с её ошибкой и время следующей.
Снова запустите эндпоинт (или снимите блокировку). Следующая попытка доставит звонок, и запись перейдёт в статус Доставлено — либо нажмите Отправить снова, чтобы доставить немедленно.

Чек-лист для вашего эндпоинта

Отвечайте 2xx, как только запрос сохранён; ресурсоёмкую обработку выполняйте после этого.
Используйте X-Hanc-Delivery-Id как ключ идемпотентности.
Отвечайте 4xx/5xx, если вы не смогли принять запрос, — мы обратимся снова.
Следите, чтобы сертификат оставался действительным, а два адреса источника — разрешёнными.

Что отправляется и когда​

Когда ваш сервер недоступен​

Расписание повторов​

Собственное расписание​

После последней попытки​

Уведомления о сбоях​

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

Сеть и файрвол​

Формат запроса​

Заголовки​

Аутентификация​

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

Переменные​

Тело запроса​

Только ваши поля​

Выборочная отправка​

Подключение тикет-системы​

Тестирование​

Чек-лист для вашего эндпоинта​