Вебхук — це спосіб для іншої програми «постукати» в Sviteya і сказати: «ось ця людина щойно щось зробила, запусти для неї воронку». Ніякого програмування для цього не потрібно: ви копіюєте одну адресу з редактора воронок і вставляєте її в налаштування зовнішнього сервісу. Типові приклади:
- людина оплатила на сайті (WordPress, Webflow, LiqPay) — бот одразу надсилає їй доступ до курсу;
- у CRM угода перейшла в статус «Оплачено» — бот дякує і пропонує наступний крок;
- заповнено Google-форму — бот вітає і ставить тег (окрема інструкція);
- ваш власний сервіс нарахував бонуси — бот повідомляє про це і показує новий баланс.
Головне, що треба знати до початку
Вебхук працює лише для людей, які вже писали вашому боту. Це обмеження не Sviteya, а самого Telegram: боти не можуть писати першими. Якщо людина ніколи не натискала «Старт» у вашому боті, повідомлення їй не дійде, і сервіс чесно відповість зовнішній системі, що контакта не знайдено (і нового контакта не створить).
Тому робочий порядок майже завжди такий: спершу людина приходить у бот → далі вона робить дію десь назовні (оплата, форма, CRM) → зовнішня система шле вебхук → бот продовжує розмову.
Крок 1. Додайте тригер «Вхідний вебхук»
- Відкрийте потрібну воронку в редакторі.
- На панелі блоків унизу, у ряду тригерів, візьміть блок «Вхідний вебхук» і перетягніть на полотно.
- Приєднайте до нього те, що має статися: повідомлення, тег, нарахування балів — будь-яку гілку воронки.
Одна воронка = одна адреса вебхука. Якщо вам потрібні різні сценарії для різних подій (окремо «оплатив», окремо «повернув гроші») — зробіть дві воронки з двома різними адресами.
Адресу вебхука бачать лише ті учасники команди, хто може редагувати воронки (власник, адміністратор, редактор). Іншим ролям блок покаже воронку без адреси.
Крок 2. Скопіюйте адресу
Одразу після збереження воронки в блоці тригера з’явиться напис «Просте посилання (без ключа)» і ваша персональна адреса вигляду:
https://app.sviteya.ai/api/hooks/whk_a1b2c3d4e5f6...Поруч є кнопка «Скопіювати посилання». Ту саму адресу можна взяти, не заходячи в редактор: на сторінці «Воронки» натисніть біля воронки «Посилання» — відкриється вікно «Вхідні посилання воронки».
Адреса — це ключ. Хто знає адресу, той може запускати вашу воронку. Не публікуйте її у відкритому коді сторінки, не викладайте в чатах і скріншотах. Адреса не змінюється при збереженнях воронки, тож налаштувати зовнішню систему достатньо один раз.
Під адресою в блоці є «Секрет підпису» з галочкою «Вимагати підпис (HMAC-SHA256)». Вона вимкнена за замовчуванням — тоді достатньо адреси. Якщо ввімкнути, запит мусить нести заголовок x-sviteya-signature: HMAC-SHA256 від тіла запиту цим секретом у шістнадцятковому вигляді (приставка sha256= теж приймається). Без правильного підпису сервіс відповість 401. Вмикайте галочку, лише коли зовнішня система вміє підписувати запити.
Крок 3. Налаштуйте, що робити з даними («мапінг»)
Зовнішня система разом із запитом може передати корисні дані: суму оплати, назву тарифу, email, номер замовлення. У блоці тригера є розділ «Дані запиту → поля контакта». Кожен рядок мапінгу — це пара:
| Ліворуч | Праворуч |
|---|---|
назва даних у запиті (наприклад email, tariff, sum) |
куди це записати: поле контакта або бали |
Що варто знати:
- Поля контакта — звичайні поля контакта. Значення просто записується поверх старого. Якщо потрібного поля ще нема, створіть його прямо тут: у списку є пункт «нове поле…».
- Бали — у тому ж списку другою групою йдуть типи балів (там же «новий тип балів…»). Для балів у рядку з’являється вибір «режим:»: додати (+), відняти (−) або встановити (=). Стандартний режим — «додати». Значення має бути числом не менше нуля, інакше рядок пропускається.
- Вкладені дані записуються через крапку. Якщо ваша CRM шле суму всередині замовлення, у полі ключа пишіть
order.total. - Якщо якогось ключа в запиті не виявилось — цей рядок мапінгу просто пропускається, воронка все одно запускається.
- Мапінг застосовується до того, як воронка почне виконуватись, тож записані значення вже можна використати в першому повідомленні.
Мапінг — річ необов’язкова. Якщо вам треба лише «запусти воронку для цієї людини», не додавайте жодного рядка. Кнопка додавання нового рядка в блоці називається «мапінг».
Крок 4. Опублікуйте воронку
Вебхук працює тільки з опублікованою й увімкненою воронкою. Чернетка не приймає запити — сервіс відповість помилкою 409 і поясне, що воронку не опубліковано або вимкнено.
Пам’ятайте: двигун щоразу читає актуальну опубліковану версію. Змінили воронку — натисніть «Опублікувати», і наступний вебхук піде вже новим шляхом.
Тестуйте після публікації. Сервіс запам’ятовує запити, щоб не виконати той самий двічі (див. «Повторні запити» нижче). Якщо ви надіслали тест до публікації й отримали 409, повтор точно такого самого тіла в найближчі 24 години буде сприйнято як дубль. Додайте в тіло будь-яке унікальне поле, наприклад event_id.
Крок 5. Вставте адресу у зовнішній системі
Що саме треба передати в запиті:
Обов’язково — хоча б один ключ, щоб сервіс зрозумів, про кого мова. Сервіс шукає людину в такому порядку, береться перший, що знайшов:
| Поле | Що це і де взяти |
|---|---|
contactId |
ID контакта в Sviteya (якщо ви його вже десь зберегли). Усередині воронок — змінна ID контакта |
personId |
ID Персони. Усередині воронок — змінна ID Персони. Якщо в цьому боті у Персони кілька контактів, сервіс не вгадує і відповідає 409 |
telegramId (або channelId) |
Номер людини в каналі бота, тільки цифри. Для Telegram-бота це Telegram ID: видно в розділі «Персони» і в картці контакта. Усередині воронок — змінна Telegram ID |
| Своє поле | У блоці тригера є розділ «кого шукати»: вкажіть ключ запиту (наприклад email) і поле контакта, з яким його порівняти. Так можна знаходити людину за поштою чи номером замовлення |
Пошук за своїм полем — запасний шлях: він спрацьовує, лише якщо за трьома ключами вище людину не знайдено. Якщо за значенням знайшлося кілька людей, сервіс нікого не обирає, відповідає 409, а причину («кілька збігів») видно в журналі вебхуків.
Решта полів — будь-які ваші, ті, які ви прописали в мапінгу.
Приклад того, що зовнішня система надсилає:
{
"telegramId": "123456789",
"email": "client@example.com",
"tariff": "premium",
"sum": 500
}Звідки взяти Telegram ID у зовнішній системі
Це найчастіше питання. Правильна схема така: спершу ви віддаєте Telegram ID назовні, потім він повертається до вас.
- У воронці, де людина йде на оплату чи залишає заявку, підставте змінну Telegram ID (кнопка «поле» біля тексту; у тексті вона виглядає як
{{field:fld_telegram_id}}) у посилання або у форму: наприклад, приховане поле форми чи параметр посилання?tgid={{field:fld_telegram_id}}. - Ваш сайт / CRM / платіжна система зберігає це значення разом із замовленням.
- Коли настає момент (оплата пройшла), та сама система шле вебхук і повертає
telegramIdназад.
Якщо ваша система не вміє зберігати Telegram ID, передайте таким самим способом змінну ID контакта ({{field:fld_contact_id}}) і повертайте її як contactId, або зберігайте пошту й користуйтеся розділом «кого шукати».
Zapier і Make
Оберіть дію «Webhooks → POST» (у Make — «HTTP → Make a request»):
- URL — адреса з кроку 2;
- Метод — POST;
- Тип даних — JSON;
- Поля —
telegramIdзі свого джерела + усе, що ви прописали в мапінгу.
Google Forms
У Google Forms немає вбудованих вебхуків, тому потрібен або посередник (Zapier / Make / n8n), або невеликий безплатний скрипт Google. Обидва способи покроково розписані в окремій інструкції: Google Forms → Sviteya.
Сайт на WordPress, Webflow, Wix
У більшості конструкторів сайтів і плагінів форм є поле «Вебхук» або «WebHook» у налаштуваннях приймачів форми: туди вставляється адреса, решта — автоматично. Якщо конструктор шле дані у власному форматі, використайте назви його полів у лівій колонці мапінгу.
Як перевірити, що все працює
- Надішліть тестовий запит із зовнішньої системи (у Zapier є кнопка «Test»).
- Відкрийте воронку — на блоках з’являться лічильники проходів.
- Перевірте картку того контакта: чи записалися значення в поля, чи змінилися бали.
- Відкрийте «Інтеграції» → «Журнал вебхуків»: там видно кожен запит — «прийнято», «дубль» або «відхилено» з причиною (невірний підпис, перевищено частоту, воронка не опублікована, контакт не знайдено, кілька збігів). Журнал зберігається 90 діб.
Якщо не працює
| Що відповів сервер | Що це означає | Що робити |
|---|---|---|
201, {"ok": true} |
Усе гаразд, воронка запущена | нічого |
201, {"ok": true, "duplicate": true} |
Такий самий запит уже був, вдруге воронка не запускається | якщо це не дубль, додайте в тіло унікальне поле (event_id) |
401 |
Увімкнено підпис, а він неправильний або його немає | перевірте секрет і заголовок x-sviteya-signature, або вимкніть галочку |
409 «Воронка не опублікована або вимкнена» |
Воронка існує, але не опублікована або вимкнена | натисніть «Опублікувати», перевірте, що воронка увімкнена |
409 «За цим значенням знайдено кілька контактів» |
Пошук за полем або personId дав кількох людей |
передайте точніший ключ: contactId або telegramId |
404 «Контакт не знайдено» |
Людини немає серед контактів цього бота | перевірте, що ключ правильний і що людина хоч раз писала боту |
404 «Unknown hook» |
Адреса невірна або воронку видалено | скопіюйте адресу заново |
429 |
Понад 300 запитів за хвилину на одну адресу | зачекайте хвилину |
| Нічого не приходить | Зовнішня система не надіслала запит | перевірте її власні логи, метод має бути POST, тип даних — JSON |
Окрема поширена причина «нічого не сталося»: воронка запустилася, але перше повідомлення не дійшло, бо людина заблокувала бота.
Повторні запити
Зовнішні системи часто надсилають той самий вебхук повторно (після збою мережі). Щоб воронка не спрацювала двічі, Sviteya відсікає повтори:
- якщо в запиті є заголовок
x-idempotency-keyабо полеevent_id, повтор з тим самим значенням протягом 30 діб вважається дублем; - якщо їх немає, дублем вважається запит з точно таким самим тілом протягом 24 годин.
Дубль отримує відповідь {"ok": true, "duplicate": true}, а в журналі вебхуків позначається як «дубль». Це стосується й запитів, відхилених із помилкою (наприклад, 409 до публікації або 404, коли людина ще не писала боту).
Часті питання
Скільки запитів можна надсилати?
До 300 запитів на хвилину на одну адресу вебхука, понад це сервіс відповідає 429. Окрема межа — з боку Telegram: близько 30 повідомлень за секунду на бота; повідомлення ставляться в чергу й просто розтягуються в часі.
Чи можна запустити воронку для людини, якої ще нема в контактах?
Ні. Telegram не дозволяє ботам писати першими — контакт має з’явитися сам.
Чи можна одним запитом запустити воронку для багатьох людей?
Ні, один запит — один контакт. Для масових сценаріїв використовуйте розсилки за тегом.
Чи змінюється адреса вебхука?
Ні. Токен видається один раз і не змінюється при збереженнях чи публікації. Копія воронки отримує свою адресу.
А якщо мені треба навпаки — щоб Sviteya стукала до мене?
Це вихідні запити: дія «HTTP-запит (вебхук)» у воронці, «Ретрансляція вебхука» в налаштуваннях бота на сторінці «Інтеграції» та вихідні вебхуки вебінарів.
Де подивитися технічні деталі: точні коди відповідей, заголовки, curl?
У розділі документації «API та MCP».