Налаштування API інтеграції

Для чого це потрібно?

Ця інструкція пояснює, як підключити вашу форму до зовнішньої системи (CRM, маркетингової платформи або власного вебхука), щоб при кожному відправленні форми дані автоматично надсилалися на вказану вами URL-адресу.

Налаштування інтеграції

У Конструкторі форм відкрийте крок Налаштування інтеграції (необов'язково). Ви побачите одне поле:

API URL інтеграції
Введіть повну веб-адресу (URL) кінцевої точки (endpoint), яка має отримати дані відправлення форми. URL має починатися з http:// або https://.

Вимоги та обмеження:

Максимум 500 символів.
Має бути валідною, публічно доступною URL-адресою.
З міркувань безпеки блокуються localhost та приватні IP-адреси (наприклад, 127.0.0.1, 169.254.169.254).
запит скасовується через 5 секунд, якщо ваш endpoint не відповідає.

Як налаштувати:

Відкрийте вашу форму в Конструкторі форм.
Натисніть крок Налаштування інтеграції (необов'язково) у бічній панелі.
Вставте URL вашого вебхука у поле API URL інтеграції.
Натисніть Зберегти (або просто перейдіть до іншого кроку — зміни зберігаються автоматично).

Примітка: Посилання «показати інформацію про інтеграцію» біля поля зараз не відображає додаткової допомоги. Це відома обмеження, яке буде виправлено в майбутніх оновленнях.

Що відбувається при відправленні форми

Після збереження URL інтеграції та активації форми, кожне відправлення ініціює POST-запит від нашого сервера на вашу URL. Тіло запиту — JSON-об'єкт зі структурою, описаною нижче.

Приклад JSON Payload

{
  "event": "form_submission",
  "form_id": "evt_abc123def456",
  "submitted_at": "2026-07-19T14:32:10.123Z",
  "answers": {
    "email_abc123": "ivan.petrenko@example.com",
    "first_name_def456": "Іван",
    "last_name_ghi789": "Петренко",
    "company_jkl012": "ТОВ \"Приклад\"",
    "newsletter_opt_in_mno345": true,
    "interests_pqr678": "Маркетинг, Продажі"
  },
  "data": {
    "fields": [
      { "id": "abc123", "label": "Email", "code": "email", "value": "ivan.petrenko@example.com" },
      { "id": "def456", "label": "Ім'я", "code": "first_name", "value": "Іван" },
      { "id": "ghi789", "label": "Прізвище", "code": "last_name", "value": "Петренко" },
      { "id": "jkl012", "label": "Компанія", "code": "company", "value": "ТОВ \"Приклад\"" },
      { "id": "mno345", "label": "Підписатися на розсилку", "code": "newsletter_opt_in", "value": true },
      { "id": "pqr678", "label": "Інтереси", "code": "interests", "value": [{ "name": "Маркетинг" }, { "name": "Продажі" }] }
    ]
  }
}

Пояснення полів

Поле	Тип	Опис
`event`	string	Завжди `"form_submission"`. Ідентифікує тип події.
`form_id`	string	Унікальний ID форми/події, яка була відправлена.
`submitted_at`	string (ISO 8601)	Точна дата та час відправлення в UTC.
`answers`	object	Плоский об'єкт ключ-значення з усіма відповідями форми. Ключі мають формат `<код_поля>_<id_поля>` (напр. `email_abc123`). Значення оброблені для зручного читання: текстові/числові → рядок; чекбокси → `true`/`false`; селекти та мультиселекти → список назв обраних опцій через кому.
`data.fields`	array	Оригінальний масив полів форми саме так, як він збережено при відправленні, з сирими значеннями (об'єкти для селектів, масиви для мультиселектів тощо). Використовуйте, якщо потрібна повна структура.

Як відбувається розгортання відповідей (`answers`)

Об'єкт answers створено для легкого парсингу у вебхуках, Zapier, Make або власному коді:

Текст, Число, Email, Телефон, URL, Текстова область → значення як рядок.
Чекбокс / Перемикач → true або false.
Select (один вибір) → name обраної опції як рядок.
Multi-select / Група чекбоксів → список name обраних опцій через кому (напр. "Маркетинг, Продажі").
Приховані / Системні поля → включаються, якщо є.

Технічні деталі (Для вашого розробника)

Якщо ви передаєте цю інформацію розробнику, який буде створювати приймаючий endpoint, надайте йому ці дані:

Метод: POST
Content-Type: application/json
User-Agent: <НазваДодатку>-Webhook/1.0 (напр. EventReg-Webhook/1.0)
Таймаут: 5 секунд (запит переривається, якщо немає відповіді)
Повторні спроби: Відсутні — помилки логуються, але автоматичного повторного надсилання немає.
Дозволені хости: Тільки публічні HTTPS endpoints. Блокуються localhost, 127.0.0.1, 0.0.0.0 та IP метаданих AWS (169.254.169.254).
Відповідь: Будь-який статус 2xx вважається успішним. Статуси, відмінні від 2xx, логуються як попередження.

Як протестувати інтеграцію

Збережіть URL інтеграції в Конструкторі форм.
Активуйте форму (натисніть Перевірити та Активувати → Активувати).
Відкрийте попередній перегляд або публічне посилання на форму і відправте тестову заявку.
Перевірте логи вашого вебхука: ви повинні бачити JSON payload зі структурою, описаною вище.

Поширені запитання

Чому мій вебхук нічого не отримав?

Переконайтеся, що форма Активна (не в стані Створено або Чернетка).
Перевірте правильність URL — має бути https://.
Переконайтеся, що ваш endpoint приймає POST з application/json.
Подивіться логи сервера на предмет таймауту 5 секунд або блокування IP.

Чи можна використовувати локальний тунель (ngrok, Cloudflare Tunnel) для тестів? Так, за умови, що публічний HTTPS URL резолвиться на ваш тунель. http:// дозволено, але https:// настоятельно рекомендовано.

Що як мій endpoint повертає помилку? Система логує HTTP-код статусу і йде далі. Автоматичного повторного надсилання немає. Ви можете вручну відправити форму знову або реалізувати механізм повторних спроб на своєму боці.

Чи можна надсилати на декілька URL? Наразі підтримується лише один URL інтеграції на форму. Якщо потрібно розсилати в кілька систем, використовуйте middleware (Zapier, Make, або власний relay-endpoint).

Чи відправляються завантажені файли? Поля завантаження файлів не включаються в payload вебхука. У data.fields присутні лише метадані поля. Самі файли залишаються в сховищі платформи.

Documentation