Статті на: Інтеграції
Ця стаття також доступна на:

Підключення вебхуку до інтернет-магазину

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

Вебхуки призначені лише для сервісів до яких необхідно надсилати інфорамацію зі сторони Weblium.

Зміст статті:
Підключення вебхуку до інтернет-магазину
Структура та опис значень з вебхуку
Перевірка власного отриманого вебхуку
Приклад отриманого вебхуку

Примітка: дані за допомогою вебхуків надсилаються у форматі JSON за допомогою POST методу.
Важливо: ця опція доступна тільки для сайтів з підпискою Unlim чи StartUp.
Підказка: ви можете дізнатися як підключити вебхуки до контактних форм у цій інструкції.

Підключення вебхуку до інтернет-магазину


Щоб підключити вебхук до вашого магазину, дотримуйтесь інструкцій нижче:
Зайдіть у налаштування сайту, відкрийте розділ Налаштування магазину і перейдіть до Сповіщень.


Натисніть на поле і введіть ваш Webhook URL для отримання даних:



Примітка: на відміну від контактних форм, до магазину наразі можливо підключити три вебхуки.

Опублікуйте свій сайт, щоб зміни набули чинності.

Готово! Тепер ви можете зробити тестове замовлення, що перевірити коректність підключення.

Важливо: зверніть увагу, що під час оформлення замовлення надсилається два сповіщення — перше про створення замовлення ("order_created"), і друге про його оплату ("order_paid", якщо вона була здійснена).

Структура та опис значень з вебхуку


Отриманий з інтернет-магазину вебхук у форматі JSON складається з багатьох записів (пар) "ключ": "значення", які містять інформацію про надіслане замовлення. Розглянемо кожну з цих пар та те, які значення вони можуть містити.

Ключ "event"


У першому записі отриманого вебхуку знаходиться назва події після якої він був надісланий. Фактично значення цього запису можна вважати назвою вебхуку.

"event" може мати лише 2 значення:
"order_created" — замовлення створене;
"order_paid" — замовлення сплачене покупцем за допомогою одного з платіжних методів.

Важливо: зверніть увагу, що якщо спочатку замовлення створюється, а потім клієнт може його сплатити. Тобто у разі сплати замовлення будуть надіслані 2 вебхуки — спочатку "order_created", а потім "order_paid". Якщо ви бажаєте після отримання вебхуків обробляти лише 1 з них, то вам необхідно додати перевірку значення ключа "event" на стороні того сервісу, що отримує ваш вебхук.

Ключ "website"


Значенням ключа "website" є об’єкт, що містить інформацію про ваш сайт: дані власника сайту, домен та назву сайту. Загалом 3 пари ключ-значення:
Ключ "owner" — має значення у вигляді об’єкту з 2 іншими ключами: "name" (ім’я користувача з налаштувань акаунта) та "username" (електронна адреса, яку ви використовуєте для входу в акаунт).
Ключ "domain" — домен або субдомен вашого сайту. Якщо до сайту не підключено власний домен (наприклад, у форматі "example.com"), то буде використано значення системного субдомену, що згенеровано під час створення сайту або вказано у його налаштуваннях (наприклад, "somename.weblium.site", де можна змінювати у налаштуваннях сайту частину "somename" з прикладу).
Ключ "name" — назва вашого сайту.

Ключ "order"


Має значення у вигляді об’єкту, який містить усю іншу інформацію про замовлення (замовлені товари, їхній опис, метод доставки та оплати тощо). Нижче послідовно розглянемо кожний з ключыв, які містяться всередині об’єкта "order", та їхні відповідні значення.

Ключ "id"

Унікальний ID вашого замовлення. Якщо у редакторі ви відкриєте ваше замовлення у налаштуваннях сайту в розділі Замовлення, то це ID буде відображено в URL після останнього слешу. Зверніть увагу, що хоч ключ у вебхуці і має назву "ID”, він не є тим самим, що "ID замовлення" у налаштуваннях вашого сайту — за вказане у налаштуваннях сайту ID відповідає ключ "code", який описано нижче.

Ключ "code"

Відповідає коду, що вказано у налаштуваннях сайту в розділі Замовлення у колонці ID замовлення. Є унікальним номером замовлення у рамках 1 сайту — на інших сайтах може бути замовлення з таким самим значенням. Кожне нове замовлення має значення на одиницю більше, ніж попереднє.

Примітка: у налаштуваннях сайту ID замовлення відображається у форматі 6 знаків з нулями до номера замовлення, наприклад, замовлення №12 буде відображене як "000012", у той час як у вебхуці ключ "code" матиме значення 12 (саме як числовий тип даних).

Ключ "status"

Відображає статус замовлення, що ви як продавець обрали в налаштуваннях сайта при перегляді замовлення після його створення. Оскільки змінити статус замовлення можна лише коли воно вже було створене (був надісланий перший вебхук "event": "order_created"), ключ "status" матиме вказаний вами статус лише за умови, що покупець створив замовлення, ви змінили його статус, і лише потім покупець сплатив це замовлення. Таким чином вже у другому надіслано після оплати вебхуці "event": "order_paid" буде передане значення вказаного вами статусу замовлення.

Відповідно у першому вебхуці "event": "order_created" ключ "status" завжди набуває значення ”new” як нове замовлення.
У другому вебхуці "event": "order_paid" ключ "status" набуває у текстовому вигляді значення статусу товару, що ви вказали при редагуванні замовлення, якщо ви це зробили до того, як клієнт сплатив це замовлення.

Перелік можливих значень ключа:
Новий — ”new”
В очікуванні — "on_hold"
В процесі — "in_progress"
Завершено — "completed"
Відміна — "canceled"

Ключ "notes"

Вказує примітку, яку ви вказали в налаштуваннях сайта при перегляді замовлення після його створення. Оскільки вказати примітку до замовлення можна лише коли воно вже було створене (був надісланий перший вебхук "event": "order_created"), ключ "notes" матиме вказане вами у примітках значення лише за умови, що покупець створив замовлення, ви додали до нього примітку, і лише потім покупець сплатив це замовлення. Таким чином вже у другому надіслано після оплати вебхуці "event": "order_paid" буде передане значення вказаної вами примітки.

Відповідно у першому вебхуці "event": "order_created" ключ "notes" завжди набуває значення null, адже не можливо додати примітку до створення замовлення.

У другому вебхуці "event": "order_paid" ключ "notes" набуває те текстове значення, що ви вказали у примітці до замовлення, якщо ви це зробили до того, як клієнт сплатив це замовлення.

Ключ "created_at"

Дата та час створення замовлення. Якщо клієнт сплатив замовлення, то у другому вебхуці "event": "order_paid" значення ключа "created_at" буде таким самим, як у першому вебхуці "event": "order_created", оскільки відображається саме час створення замовлення.

Відображається у форматі ISO 8601: "yyyy-MM-ddTHH:mm:ss.SSSZ". Тобто зліва направо: рік, місяць, день, літера "T", години, хвилини, секунди, мілісекунди, літера "Z". Приклад: ”2023-01-11T08:45:46.626Z”.

Важливо: при вказівці дати й часу використовується часовий пояс UTC+00:00.

Ключ "shipment"

Ключ "shipment" має у якості значення об’єкт з описом обраного методу доставки. Усередині цього об’єкту знаходяться наступні ключі:
"id" — унікальний ідентифікатор методу доставки. Якщо у декількох замовленнях обрати однаковий метод доставки, то цей ID в них теж буде однаковим. Не змінюється після редагування методу доставки.
"name" — назва методу доставку, яку ви вказали у налаштуваннях вашого сайту.
"price" — вказана вами у налаштуваннях ціна доставки у числовій формі. Якщо доставка безкоштовна, то цей ключ має значення 0
Важливо: ціна доставки завжди вказується у 100 разів більшою задля того, щоб позбутися можливої крапки між цілою та дробовою частиною числа. Тобто якщо ціна доставки складає "15", то в отриманому вебхуці буде значення 1500. Інший приклад: ціна доставки — "42,55", в отриманому вебхуці — 4255.
"address" — адреса самовивозу товару. Має значення лише якщо покупцем був обраний варіант доставки “Самовивіз із магазину”. Якщо був обраний варіант “Кур’єрська доставка”, то значення ключа є порожній об’єкт ("address": {}). У разі вибору методу доставки “Самовивіз із магазину”, значенням ключа "address" є об’єкт з 3-ма іншими ключами:
⠀⠀⠀• "id" — унікальний ID цієї адреси у цьому методі доставки. Якщо ви відредагуєте у налаштуваннях сайту метод доставки, то цей ID буде згенеровано заново.
⠀⠀⠀• "name" — завжди набуває значення "address"
⠀⠀⠀• "description" — назва обраної покупцем адреси для самовивізу з випадного списку (у налаштуваннях методу доставки “Самовивіз із магазину” ви можете вказувати декілька адрес з-поміж яких зможуть обирати покупці).
"description" (зверніть увагу, що це вже "description" як ключ об’єкту "shipment", а не ключ об’єкту "address", як у попередньому абзаці) — цей ключ містить примітки (опис), які ви вказали для цього методу доставки у його налаштуваннях.
"address_custom" — адреса доставки, яку вписав покупець для кур’єрської доставки. Надсилається лише якщо покупець обрав метод доставки з типом “Кур’єрська доставка”.
"order_includes_price" — чи враховується вартість доставки у сумі замовлення (тобто чи активований перемикач “З урахуванням вартості доставки” у налаштуваннях методу доставки. Може набувати 2 булевих значення: true (якщо згаданий перемикач активовано) або false (якщо перемикач вимкнений). Зверніть увагу, що якщо якщо активувати перемикач “З урахуванням вартості доставки”, але не вказати ціну доставки або ж вказати 0, то у кошику буде відображатися вартість методу доставки як “Безкоштовно”, значення "price" у вебхуці теж буде 0, проте значення "order_includes_price" вже буде true (тобто у суму замовлення включена вартість 0 за доставку).

Наводимо 2 приклади коду ключа "shipment". Приклад коду з методом доставки “Самовивіз із магазину”:
"shipment": {
      "id": "69b3132a-f7e0-4e99-a4b5-d4fad1b286a8",
      "name": "Самовивіз із магазину (назва)",
      "price": 4255,
      "address": {
        "id": "75212c5b-9bad-4fd2-aa34-6af2b7ee0c67",
        "name": "address",
        "description": "вул. Хрещатик, 1, Київ, Україна"
      },
      "description": "Опис методу доставки",
      "order_includes_price": true
}


Приклад коду з методом доставки “Кур’єрська доставка”:
"shipment": {
      "id": "3582e89e-de9b-4829-b69e-23fc8d866ec5",
      "name": "Кур’єрська доставка (назва)",
      "price": 1500,
      "address": {},
      "description": "Опис кур’єрської доставки",
      "address_custom": "вул. Гарматна, 5, Київ",
      "order_includes_price": true
}


Ключ "products"

Містить масив (впорядкований список елементів), де кожний елемент це об’єкт з інформацією про обраний покупцем товар. Тобто схематично ця частина виглядає наступним чином:
"products": [
   {
        "ключ-1": "значення-1",
        "ключ-2": "значення-2",
        // наступні ключі та їхні значення для ПЕРШОГО замовленого товару.
    },
   {
        "ключ-1": "значення-1",
        "ключ-2": "значення-2",
        // наступні ключі та їхні значення для ДРУГОГО замовленого товару тощо.
    }
]


Розглянемо які ключі та відповідні значення містяться у кожному об’єкті товару:
"name" — назва товару.
"sku" — артикул товару.
"code" — унікальний код товару.
Примітка: у налаштуваннях сайту код товару відображається у форматі 6 знаків з нулями до коду товару. Наприклад, товар із кодом у налаштуваннях сайту "000012" буде мати у вебхуці значення 12 (саме як числовий тип даних).
"slug" — частина URL товару після останнього слешу (тобто після .../shop/). Наприклад, у товару з посиланням https://example.com/shop/sample-product це буде sample-product.
"slug_id" — унікальний ID, який характеризує поточний "slug" товару, описаний у попередньому пункті.
"description" — опис товару. Перенесення рядків відображається символом \n
"status" — наявніть товару. Може набувати 1 з 3 значень, залежно від того, який статус наявності ви обрали у налаштуваннях товару: "in_stock" (є у наявності), "available_for_order" (передзамовлення) та "coming_soon" (очікується, що товар незабаром буде у наявності).
"meta_description" — вказаний у вкладці SEO в налаштуваннях товару опис сторінки (якщо це значення вказано у налаштуваннях товару, воно також відображається в коді сторінки у атрибуті “content” мета-тегу <meta name="description" content="example">).
"meta_keywords" — ключові слова, що вказані у вкладці SEO в налаштуваннях товару.
"meta_no_index" — чи заборонена індексація цього конкретного товару у налаштуваннях цього товару. Може набувати 2 булевих значення: true або false
"meta_no_follow" — чи заборонено пошуковим системам переходити за посиланнями на цій сторінці (true або false).
"meta_seo_title" — вказаний у вкладці SEO в налаштуваннях товару заголовок сторінки (якщо це значення вказано у налаштуваннях товару, воно також відображається в коді сторінки у тезі <title>).
"attributes" — містить масив із переліком атрибутів товару. Кожний елемент масиву є об’єктом із 3 ключами всередині:
⠀⠀⠀• "name" — вказана у налаштуваннях товару назва атрибуту;
⠀⠀⠀• "type" — обраний у налаштуваннях товару тип атрибуту. Може набувати 4 значення: "brand", "gender", "age_group" (запропоновані системою типи атрибутів) або ж null (якщо ви додали кастомний атрибут). При цьому перші 3 запропоновані системою атрибути є унікальними, тобто, наприклад, немає можливості додати до товару 2 атрибути "brand" тощо.
⠀⠀⠀• "value" — вказане у налаштуваннях товару значення атрибуту;
"amount" — ціна одиниці товару.
Важливо: ціна товару завжди вказується у 100 разів більшою задля того, щоб позбутися можливої крапки між цілою та дробовою частиною числа. Тобто якщо ціна складає "65", то в отриманому вебхуці буде значення 6500. Інший приклад: ціна товару — "10,99", в отриманому вебхуці — 1099.
"qty" — обрана покупцем кількість товару, яку він бажає придбати.
"option_values" — містить масив із переліком обраних покупцев опцій (варіантів) товару, якщо товар є варіативним (той, де покупець може обрати колір, матеріал або інші варіанти). Кожний елемент масиву є об’єктом із 2 ключами всередині, які описують обраний покупцем варіант:
⠀⠀⠀• "name" — вказана вами у налаштуваннях товару назва опції (наприклад, “Матеріал” або “Колір”);
⠀⠀⠀• "value" — обране вашим покупцем значення цієї опції з випадного списку на сторінці товару (наприклад, якщо клієнт обирає колір, то цей ключ може мати значення “Червоний”, “Синій” тощо).
"preview" — містить посилання на головне зображення товару. Для завантаження і перегляду зображення необхідно додати наприкінці посилання /original. Наприклад, якщо значення ключа є "//e-c.storage.googleapis.com/res/e779bde7-b354-4636-8892-3db4e9e86284", то для завантаження зображення необхідно перейти за посиланням //e-c.storage.googleapis.com/res/e779bde7-b354-4636-8892-3db4e9e86284/original. Також звертаємо увагу, що зображення завантажується без розширення файлу, тому для його перекладу необхідно додати наприкінці завантаженого файлу ".png" чи ".jpg" абощо.
"formatted" — містить об’єкт із 2 відформатованими значеннями ціни товару та суми усіх придбаних одиниць цього товару. Ці значення відображаються у тому ж вигляді, що у вас на сайті, наприклад, "210,00 грн". Нижче перелік цих 2 згаданих ключів та їхніх значень:
⠀⠀⠀• "amount" — ціна поточного товару;
⠀⠀⠀• "total_amount" — сума усіх замовлених покупцем одиниць цього товару. Наприклад, якщо ціна одиниці товару 50$ і покупець замовив 3 одиниці саме цього товару, то значення "total_amount" буде "150$".

Ключ "custom_fields"

Містить об’єкт із переліком полів з кошику та відповідних значень, що увів покупець під час створення замовлення. У якості ключів у цьому об’єкті виступають назви полів кошику, які ви вказали у налаштуваннях сайту в налаштуваннях інтернет-магазину в вкладці Кошик. У якості значень відображається текст уведений (або обраний з випадного списка) покупцем під час оформлення замовлення.

Приклад JSON-коду ключа "custom_fields" з заповненими полями усіх 7 можливих типів поля (в отриманому вебхуці тип поля не вказується, тому фактично кожне поле відображається в однаковому форматі):
"custom_fields": {
      "Short text": "Example of the short text",
      "Name": "Name Example",
      "Email": "myemail@gmail.com",
      "Phone": "+380441234567",
      "Comment": "Example of the comment",
      "Long text 1": "Old cherry garden near the house\nAnd beetles buzzing in green leaves,\nThe plowers carrying their plows,\nAnd mothers cooking supper meals.",
      "Dropdown list": "Option name 1"
}


Назви ключів ("Short text", "Name" тощо з прикладу) це назви полів кошика, які вказуються у налаштуваннях сайту його власником.

Ключ "gateway"

Містить об’єкт з описом обраного покупцем платіжного методу. Цей об’єкт містить 3 ключа:
"id" — унікальний ідентифікатор доданого вами платіжного методу.
"type" — вказує на тип платіжного методу, тобто саме назву платіжної системи, до якої належить обраний покупцем платіжний метод. Наприклад, це можуть бути значення "fondy", "liqpay", "monobank" тощо. Якщо обрано платіжний метод “Вручну” (тобто той, де ви в налаштуваннях сайту текстом описали що це за платіжний метод, без онлайн-оплати покупцем через певну платіжну систему), тоді буде вказане значення "type" як "offline". Значення цього ключа задані системою та не змінюються користувачем.
"name" — вказана вами у налаштуваннях сайту назва платіжного методу.

Ключ "formatted"

Містить об’єкт з відформатованими значеннями суми вартості усіх товарів, доставки та загальної суми замовлення з урахуванням доставки. Ці значення відображаються у тому ж форматі, що вартість товарів на сайті, наприклад, "210,00 грн". Відповідно 3 ключі:
"subtotal_amount" — сума усіх замовлених покупцем товарів. Наприклад, якщо покупець придбав 2 товари за 50$ та 1 за 20$, то значення "subtotal_amount" буде "120$".
"total_amount" — загальна вартість замовлення з урахуванням доставки. Наприклад, якщо замовлено декілька товарів на суму 400 грн, а вартість доставки складає 60 грн, тоді значення "total_amount" буде "460 грн".
"shipment_amount" — вартість доставки замовлення, наприклад, "60 грн".

Перевірка власного отриманого вебхуку


Якщо ви бажаєте переглянути як буде виглядати вебхук саме з вашого інтернет-магазину, то ви можете це зробити за допомогою сторонніх сервісів, наприклад, webhook.site або ngrok.com. Розглянемо це на прикладі сервісу webhook.site:
Відкрийте webhook.site та праворуч від поля Your unique URL натисність на кнопку Copy to clipboard:


Під'єднайте це посилання у налаштуваннях вашого сайту за допомогою першого розділу цієї статті:


Відкрийте ваш інтернет-магазин, додайте певний товар або товари до кошику та створіть замовлення. Для прикладу нижче ліворуч відображений доданий до замовлення товар, а праворуч — заповнений покупцем кошик:


Після створення замовлення поверніться до webhook.site, де ви знайдете отриманий вебхук з усіма значеннями про створене замовлення:


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

Приклад отриманого вебхуку


Нижче наведено приклад отриманого вебхуку з попереднього розділу:
{
  "event": "order_created",
  "website": {
    "owner": {
      "name": "myName",
      "username": "support@weblium.com"
    },
    "domain": "llwtc.weblium.site",
    "name": "For help center main"
  },
  "order": {
    "id": "b95a46ac-97df-43d2-909d-bbab4e8fe3b0",
    "code": 72,
    "status": "new",
    "notes": null,
    "created_at": "2023-01-13T18:34:29.505Z",
    "shipment": {
      "id": "b79a00eb-8b7f-40f3-8f91-825495c9b658",
      "name": "Pick up from the store",
      "price": 1500,
      "address": {
        "id": "638cdbab-5b11-43cb-be80-964425b55f8c",
        "name": "address",
        "description": "My test address, Great str., Kyiv, Ukraine"
      },
      "description": "Description of this shipment method.",
      "order_includes_price": true
    },
    "products": [
      {
        "name": "Product name example",
        "sku": "123",
        "code": 26,
        "slug": "sample-barr-armchair-dodo-design-bureau",
        "slug_id": "5f731d135a5a26485c272910",
        "description": "Some text text text.\nNew row\n\nNew row with a space above.",
        "status": "coming_soon",
        "meta_description": "Example of the SEO description",
        "meta_keywords": "keyword1, keyword2",
        "meta_no_index": false,
        "meta_no_follow": false,
        "meta_seo_title": "Example of the SEO title",
        "meta_generated_seo_title": null,
        "attributes": [
          {
            "name": "Age",
            "type": "age_group",
            "value": "10+"
          },
          {
            "name": "My custom attribute",
            "type": null,
            "value": "The value of my custom attribute"
          }
        ],
        "amount": 49000,
        "qty": 1,
        "option_values": [
          {
            "name": "Color",
            "value": "Red"
          },
          {
            "name": "Material",
            "value": "Wood"
          }
        ],
        "preview": "//e-c.storage.googleapis.com/res/e779bde7-b354-4636-8892-3db4e9e86284",
        "formatted": {
          "amount": "490$",
          "total_amount": "490$"
        }
      }
    ],
    "custom_fields": {
      "Name": "My test name",
      "Email": "testemail@example.com"
    },
    "gateway": {
      "id": "df2de136-e51a-4df8-8889-9d85b99ec241",
      "type": "offline",
      "name": "Cash"
    },
    "formatted": {
      "subtotal_amount": "490$",
      "total_amount": "505$",
      "shipment_amount": "15$"
    }
  }
}

Оновлено: 07/12/2023

Чи була ця стаття корисною?

Поділіться своїм відгуком

Скасувати

Дякуємо!