Вебхуки

Вебхук — адреса вашої системи, куди магазин сам надсилає подію, щойно вона сталася: нове замовлення, оплату, ТТН, зміну залишку. Так замовлення потрапляють у BAS чи 1С, рядок — у Google Таблицю, повідомлення — у сценарій Make, n8n чи Zapier. Окремої інтеграції для кожної системи не треба: вистачає адреси, яка приймає HTTP-запити. Вхідний вебхук — навпаки: адреса магазину, на яку інша система надсилає залишки, ціни, статуси, ТТН, товари, клієнтів чи замовлення.

Вебхуки — у Налаштування → Вебхуки: вкладки Вихідні, Вхідні й Журнал доставок. Для BAS/1С, Google Таблиць, Telegram, Make, n8n і Zapier є готові шаблони в Налаштування → Інтеграції (див. «Інтеграції»). Розділ бачать і налаштовують власник і адміністратори магазину.

На якому тарифі

Вебхуки — з тарифу «Бізнес»: 5 адрес і 10 000 подій на добу; на «Про» — 20 адрес і 100 000 подій. Адреса — це вихідний чи вхідний вебхук; подія — одне надсилання на одну адресу і кожен вхідний запит. Повтори після помилок і тестові події не рахуються.

Угорі сторінки видно, скільки адрес зайнято, скільки подій пішло сьогодні й скільки чекає. Коли ліміт доби вичерпано, нові події не губляться: чекають у черзі й підуть після 00:00 за київським часом. На тарифі без вебхуків розділ показує таблицю тарифів і пропонує перейти на «Бізнес».

Як створити вебхук

1. Налаштування → Вебхуки → + Вебхук.
2. Назва (як ви впізнаєте його в списку) і Адреса вашої системи: https:// чи http://, без логіна й пароля в ній. Магазин надсилає лише на сайти в інтернеті: адреси локальної мережі, localhost і подібні не приймаються ні при збереженні, ні під час надсилання.
3. Позначте події й за потреби умови (нижче).
4. Створити вебхук — і сторінка покаже секрет підпису. Скопіюйте його одразу: повністю його більше не покажемо.

Перемикач у списку чи внизу сторінки вебхука вимикає надсилання: поки вебхук вимкнено, нові події на нього не йдуть. Видалити вебхук прибирає його разом із секретом і журналом.

Події й умови

Галочка біля події — і вона йтиме щоразу. Умова необов'язкова: + умова під подією додає рядок «Лише коли…» — поле, порівняння й значення, — наприклад, лише оплачені замовлення понад 1 000 ₴ або зміну статусу лише на «Відправлене». Умов у події може бути кілька (до 10) — тоді мають виконатися всі; × прибирає умову. В умовах замовлень є сума (у гривнях: «1000», «1 990,50»), статус, спосіб оплати, оплата частинами, джерело (сайт, Prom, Rozetka, інша система), доставка й артикул товару в замовленні; у товарів — артикул, залишок і стан; у клієнтів — група покупців. Умова на артикул у замовленні виконується, коли він є хоча б в одному рядку; «не» — коли його немає в жодному.

Перевірка умов на останніх замовленнях показує оцінку — скільки запитів пішло б за минулі 7 днів — і останні замовлення з позначкою «надішлемо» чи «ні» з умовою, яка зупинила.

Для подій записів умова — назва послуги. Скасування запису приходить двома подіями: booking.status_changed і booking.cancelled — підпишіться на ту, яка зручніша.

Формат даних

Магазин надсилає POST із JSON версії v1: id події, type, version, created_at (з часовим поясом магазину, 2026-10-24T14:32:08+03:00), test і data — замовлення, товар, клієнт, заявка, відгук чи запис. Гроші — цілі копійки (total_kopecks: 298000 — це 2 980 ₴). Приклад для кожної події з заголовками — на вкладці Формат вебхука.

У замовленні: номер, статус і його назва, етап, суми, оплата, покупець, товари з опціями («Розмір: M»), доставка, ТТН, коментар і посилання на картку в конструкторі. Суми складаються так:

total_kopecks = subtotal_kopecks − знижка промокоду − знижка «Запроси друга» чи до дня народження − points_discount_kopecks (оплачене балами) + shipping_kopecks.

subtotal_kopecks — товари після акцій і цін групи покупця; discount_kopecks — усе, що знято з цін сайту (акції, ціни групи, промокод, бонусні знижки). source — site, prom, rozetka чи external (інша система).

Версія v1 не ламається: поля не зникають і не перейменовуються, нові лише додаються. Якщо колись знадобиться несумісна зміна, вона вийде окремою версією, і перемкнете її ви самі.

Підпис і секрет

Кожен запит підписано HMAC-SHA256 вашим секретом. Заголовок X-AIB-Signature має вигляд t=1792827128,v1=…: перевірте, що HMAC від рядка «t.тіло запиту» збігається з одним із v1, а час t не старший за 5 хвилин. Тоді запит точно від магазину, навіть якщо адресу хтось дізнався. Інші заголовки: X-AIB-Event (тип), X-AIB-Event-Id (той самий у всіх повторах), X-AIB-Delivery. Приклади перевірки для Node.js, PHP і BAS/1С — на вкладці Захист і повтори.

Новий секрет показуємо один раз. Добу після заміни запити підписано обома секретами — старим і новим, — тож ваша система встигне перейти без збоїв.

Повтори й пауза

Успіх — відповідь 2xx протягом 10 секунд (переадресація — це відповідь, а не перехід; виняток — Apps Script Google Таблиць). Інакше магазин повторює: через 1 хв, 5 хв, 30 хв, 2 год і 12 год — 6 спроб. Якщо адреса не відповідає добу, вебхук стає на паузу: команда магазину отримує лист і повідомлення в Telegram, а нові події тримаємо 7 днів. Відновити й надіслати (у банері над списком чи на сторінці вебхука) знімає паузу й надсилає збережене.

Повтор може прийти пізніше за новішу подію, тож порядок визначайте за created_at. Той самий id вдруге — це повтор, його можна пропустити. Відповідайте 200 одразу, а обробляйте у фоні.

Тестова подія

Надіслати тестову подію на сторінці вебхука: виберіть подію й дані — останній запис магазину, замовлення за номером або вигаданий приклад. Подія йде як справжня, з підписом; галочка Позначити як тест додає "test": true, щоб ваша система не створила справжній документ. Відповідь адреси видно одразу, разом із тим, що саме надіслали, а тест — у журналі з позначкою «тест». Тестові події не рахуються в ліміт доби.

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

Вебхуки → Журнал доставок (і вкладка Журнал вебхука): час, подія, адреса, відповідь, тривалість і спроба. Фільтри — за вебхуком, подією, періодом (24 години, 7 чи 30 днів) і пошуком за номером замовлення чи артикулом. Клацніть подію — побачите, що саме надіслали й що відповіла адреса, кожну спробу й кнопку Скопіювати як curl, щоб програміст повторив запит у себе (підпис у ній свіжий і діє 5 хвилин).

Лише невдалі дає позначити кілька доставок і Надіслати ще раз — з новими 6 спробами. Журнал зберігаємо 30 днів; унизу — що найчастіше не так за тиждень. Якщо покупець попросив видалити свої персональні дані, тіла подій про нього (замовлення, записи й заявки з його телефоном чи email, відгуки) стираються, а невідправлені — більше не надсилаються; у журналі лишається рядок з поясненням.

Вхідні вебхуки

Налаштування → Вебхуки → Вхідні → + Вхідний вебхук: три кроки — дія, поля, адреса й захист — і передайте адресу тому, хто налаштовує іншу систему. Адреса має вигляд https://api.<домен>/api/v1/hooks/<секрет>.

Кожна дія — окремий вебхук зі своєю адресою; вхідні займають адреси тарифу разом із вихідними, а кожен запит рахується в події доби. Вебхук діє від імені магазину, права співробітника йому не потрібні — усе видно в журналі, а в історії замовлення — запис «Вхідний вебхук «назва»». Залишки, ціни, товари й клієнти, змінені вхідним вебхуком, не надсилаються назад вихідними: система, що їх надіслала, уже знає. Статус, ТТН і нове замовлення йдуть звичайним шляхом магазину — листи покупцю, сповіщення команді, інші вебхуки.

Наш формат вхідних

POST із JSON: { "action": "stock.update", "items": [ … ] } — до 1 000 рядків (масив без обгортки чи один рядок теж підходять). Гроші — цілі копійки (price_kopecks: 249000 — це 2 490 ₴), залишок — ціле число. Поле action необов'язкове, але якщо є — мусить збігатися з дією вебхука.

• залишки: { "sku": "SV-M", "stock": 12, "price_kopecks": 249000 };
• ціни: { "sku": "SV-M", "price_kopecks": 249000, "old_price_kopecks": 279000, "group_prices": [{ "group": "Опт", "price_kopecks": 199000 }] } — групу шукаємо за назвою без урахування регістру; невідома група зупиняє рядок, і нічого в ньому не змінюється; стара ціна 0 — прибрати її;
• статус: { "number": 1043, "status": "shipped" } — код статусу з «Налаштування → Статуси замовлень»;
• ТТН: { "number": 1043, "ttn": "20450012345678", "carrier": "nova_poshta" } — без carrier перевізника визначаємо за номером (13 символів — Укрпошта, 14 цифр — Нова Пошта); та сама ТТН удруге на тому самому замовленні — не помилка;
• товар: { "sku": "SK-140", "name": "Скатертина лляна", "price_kopecks": 129000, "stock": 9, "description": "…" };
• клієнт: { "phone": "+380671234567", "first_name": "Олена", "last_name": "Коваль", "email": "[email protected]" };
• замовлення: { "external_id": "A-1001", "customer": { "phone": "+380671234567" }, "lines": [{ "sku": "SV-M", "quantity": 1 }], "delivery": "Нова Пошта, Львів, №12", "paid": false } — одне замовлення на external_id: повторний запит знайде вже створене, а не зробить друге. Без ціни рядок бере ціну сайту, склад списується одразу (навіть якщо товару не вистачає — тоді замовлення позначено «Потребує уваги»);
• кілька дій: { "action": "batch", "actions": [{ "action": "order.status", "items": [ … ] }, { "action": "order.ttn", "items": [ … ] }] } — рядки нумеруються наскрізь.

Свій формат і перевірка на прикладі

Якщо система не вміє надсилати наш формат (типова 1С, склад, таблиця), виберіть Свій формат — зіставити поля, вставте приклад того, що вона надсилає, і зіставте поля: звідки брати рядки («Рядки з») і яке поле прикладу йде в артикул, залишок, ціну. Щойно ви вставите приклад, магазин сам пропонує зіставлення за звичними назвами полів («Артикул», «Залишок», «Ціна», sku, qty…). Ціни читаємо так, як пише інша система, — «2 490,00» стане 2 490 ₴; порожній залишок за галочкою порожньо = 0 — 0. Замовлення й «Кілька дій» — лише в нашому форматі.

Перевірити на прикладі показує кожен рядок: що зміниться (залишок, ціна, статус, ТТН), які не знайдено й чому — і відповідь, яку отримає система. Нічого в магазині при цьому не змінюється.

Адреса, підпис і дозволені IP

Секрет — частина адреси: без нього запит не приймаємо. Якщо адреса потрапила не в ті руки, натисніть Нова адреса — стара перестане діяти одразу. Для вимогливіших систем увімкніть Перевіряти підпис HMAC-SHA256: запит мусить мати заголовок X-AIB-Signature у тому самому вигляді, що й наші вихідні (t=…,v1=… від t.тіло із секретом вебхука). Дозволені IP обмежать адреси, з яких приймаємо, — окремі IP чи діапазони на зразок 91.200.12.0/24 (до 20); порожньо — з будь-якої адреси.

До 1 000 рядків у запиті й 60 запитів за хвилину на одну адресу.

Відповідь і журнал вхідних

На прийнятий запит відповідаємо 200 з результатом: { "ok": true, "updated": 120, "not_found": 3, "failed": 1, "errors": [{ "row": 17, "key": "XX-99", "code": "not_found", "field": "sku", "error": "sku: not found" }] } — рядок із помилкою не зупиняє решту. Коди рядків: not_found, required, invalid, bad_phone, unknown_status, same_status, closed, waybill, waybill_taken, line_not_found, no_lines, order_limit, action; unavailable — магазин тимчасово не зміг застосувати рядок, надішліть його ще раз. Відмовлений запит — 404 (немає такої адреси чи вебхук вимкнено), 401 (підпис), 403 (IP), 402 (тариф без вебхуків), 429 (ліміт подій на добу чи 60 запитів за хвилину), 413 (понад 1 000 рядків) чи 400 (не JSON або інша дія) — і, крім відмов за частотою, теж потрапляє в журнал.

Вкладка Журнал вхідного вебхука: час, звідки, скільки рядків і що з ними сталося. Клацніть запит — побачите рядки, які не застосовано, і чому; Завантажити ці рядки (CSV) віддасть їх таблицею, а Повторити запит застосує той самий запит ще раз — після того, як ви додали відсутній товар чи виправили зіставлення (без перевірки IP і підпису: повторюєте ви самі). Журнал вхідних зберігаємо 30 днів.