> Усі статті WIKI Helomi: /wiki/llms.txt

# Webhook

Інтеграція Webhook з'єднує Helomi з будь-яким сервісом у дві сторони. Вхідні вебхуки приймають дані з сайту, форми чи іншого сервісу (WooCommerce, Contact Form 7, Weblium, Facebook Leads через Apix-Drive, WIX) і за вашим мапінгом створюють контрагента, угоду й завдання. Вихідні — це тригери з дією Webhook: коли в CRM стається подія, дані йдуть в інший сервіс (SMS, Viber, Telegram, залишки…).

## Можливості
- Скільки завгодно вхідних вебхуків, у кожного своя адреса.
- Шаблони: «Webhook без налаштувань», «WooCommerce (кошик)», «WordPress (Contact Form 7)», «Weblium (форми)», «Weblium (кошик)», «Facebook Leads (Apix-Drive)», «WIX (форми)».
- Мапінг змінних запиту в поля контрагента (завжди), угоди (з товарами) і завдання; захист від дубля угоди за ID замовлення.
- «Історія запитів»: змінні з тіла кліком у мапінг, «Перевірити мапінг», «Обробити ще раз».
- Вихідні тригери на таблиці «Угоди», «Контрагенти», «Завдання», «Журнал операцій», «Фінанси», «Нотатки», «Доставка» з умовою, запуском відразу, із затримкою або за датою, і журналом спрацювань.

## 1. Налаштування
Дорога до вхідних: «Налаштування» → «Інтеграції» → вкладка «Інше» → картка «Webhook»; або «Налаштування → Автоматизація → Вхідні вебхуки». Дорога до вихідних: «Налаштування → Автоматизація → Тригери (Webhook)».

Дивитися може кожен з доступом до «Інтеграцій»; створювати й змінювати — адміністратор або людина з доступом до «Налаштувань CRM». Ключів у картці нема («Ключ доступу: Не потрібен.»). «Стан роботи» показує «Вхідних вебхуків: N з M увімкнено» і «Тригерів Webhook: N з M увімкнено».

Ключі сторонніх сервісів для вихідних тригерів (напр. токен SMS-сервісу) у тексті тригера не пишуться: вони задаються на сервері як `CRM_SECRET_<НАЗВА>` і вставляються змінною `{{secrets.НАЗВА}}`; у журналі вони приховані.

## 2. Створити вхідний вебхук
1. Картка «Webhook» → блок «Вхідні вебхуки» → «+ Новий вебхук».
2. Оберіть шаблон сервісу або «Webhook без налаштувань».
3. Вебхук з'явиться в таблиці («Назва», «Шаблон», «Запитів», «Останній»). Відкрийте його: «Назва вебхука», перемикач «Приймає запити» / «Вимкнено», адреса для сервісу зі «Скопіювати».
4. Вставте адресу в налаштування вебхука на сайті чи в сервісі й надішліть тестовий запит (заповніть форму як клієнт).
5. «Нова адреса» генерує іншу адресу; стара перестане приймати запити — її треба замінити в сервісі.
6. «Зберегти». «Видалити вебхук» — прибрати.

## 3. Мапінг: контрагент, угода, завдання
- **Контрагент** (створюється завжди): «Тип контрагента» (Лід / Клієнт), «Головний відповідальний», «Джерело», «Статус ліда (ID)», «Теги (через кому)», «Наявний контрагент» (що робити, якщо такий уже є), і таблиця «Поле CRM» ← змінна; «+ Додати змінну». Обов'язково — «Назва компанії» або «Контактна особа».
- **«Створювати угоду»**: обов'язково «Назва угоди»; «ID замовлення» не дасть створити дубль. «Воронка», «Етап», «Товари» — масив товарів у запиті і чотири стандартні змінні елемента (назва, кількість, ціна, артикул); артикул шукається на складі.
- **«Створювати завдання»**: обов'язково «Назва завдання» (чітка назва в скісних рисках, напр. `/Передзвонити/`), «Термін, хвилин від запиту».

Синтаксис змінних: `a.b`, `a[].b`, `a[1].b`, `$.x`, `/текст/` (постійний текст), `{{a}} {{b}}` (склеїти кілька).

## 4. Історія запитів і повторна обробка
У вебхуку — «Історія запитів»: «Дата», «Що сталось», «Результат», «Тіло» («показати»). «Змінні» — назви полів з тіла запиту; клік вставляє змінну в поле мапінгу. «Перевірити мапінг» показує результат без створення записів. «Обробити ще раз» — обробити запит за поточним мапінгом. Якщо запит не вдалося обробити, нічого не створюється, а причина пишеться в історії.

## 5. Вихідні: тригер з дією Webhook
1. «Налаштування → Автоматизація → Тригери (Webhook)» → «+ Новий тригер» або «З шаблону…» (Viber і SMS через TurboSMS, SMS Club, AlphaSMS, Telegram, Хорошоп, Kasta, рух товару та інші).
2. «Назва», «Таблиця з даними», «Умова виконання» (напр. `stage.name == 'Відправлено'`, `result == 'successful'`, `AND` / `OR`), «Метод запуску» («Відразу», «З затримкою» — «Затримка, хвилин», «На основі поля з типом дата» — поле, «До дати» / «Після дати», дні, година).
3. Дія: «URL», «Метод відправки», «Content-Type», «Успішний статус запиту», «Заголовки запиту (Headers)», «Параметри запиту (Params)», «Тіло запиту (Body)» зі змінними (товари — `{{#jobs}}…{{/jobs}}`), «Успішна відповідь (Response)» — значення з відповіді в поле запису.
4. «Перевірка» → «Виконати на записі» — пробний запуск. «Журнал спрацювань» — останні 100 спрацювань; ключі в запитах приховано.

Імпорт і дзеркало KeepinCRM тригерів не запускають; тригер спрацьовує лише на нові дії. Докладно про тригери — [Налаштування: тригери](settings-triggers.md).

## Можливі помилки
| Що ви бачите | Чому | Що зробити |
| --- | --- | --- |
| «Контрагент: не налаштовано поле «Назва компанії» або «Контактна особа» — без нього нічого не створиться» | У мапінгу нема назви контрагента | Додайте змінну в одне з цих полів |
| «Угода: не налаштовано поле «Назва угоди»» | Увімкнено «Створювати угоду» без назви | Задайте змінну або текст для назви |
| «Завдання: не налаштовано поле «Назва завдання»» | Те саме для завдання | Задайте назву |
| «не заповнено «Назва компанії / Контактна особа» — перевірте змінні контрагента» | Змінна в запиті порожня | Перевірте назви змінних в «Історії запитів» |
| «поле «…» — цифрове, а прийшло «…»» | Текст у числовому полі | Змініть змінну або тип поля |
| «поле «…» — Так/Ні, а прийшло «…»» / «— дата, а прийшло «…»» | Значення не того типу | Виправте мапінг |
| «додаткового поля «…» нема — оновіть мапінг» | Поле видалили з налаштувань | Оберіть інше поле |
| «етапу «…» нема у вибраній воронці» | Етап перейменовано чи видалено | Оберіть етап заново |
| «external_uid «…» вже зайнятий — угода #… уже створена раніше» | Повтор того самого замовлення | Нічого робити не треба: дубль не створено |

## Для ШІ-співробітників
5`). Записи, створені вебхуком, ШІ бачить у «Клієнтах», «Угодах», «Завданнях» звичайними інструментами. Статтю ШІ читає інструментом `help("int-webhook")`.

## Додаткова інформація
- Пов'язані статті: [Вебхуки](settings-webhooks.md), [Налаштування: тригери](settings-triggers.md), [Сайти](int-sites.md).