Огляд
Neocarts надсилає POST на сервер магазину щоразу, коли щось сталося із замовленням, підпискою чи платежем. Так магазин дізнається про те, чого не бачить зі свого боку: оплату, продовження підписки, паузу, повернення грошей. Опитувати Shop API не потрібно.
Як увімкнути
Section titled “Як увімкнути”-
Відкрийте в панелі магазину Налаштування → Інтеграція, розділ «Вебхуки».
-
Вкажіть «URL для вебхуків» — адресу, на яку Neocarts надсилатиме
POST. У продакшені — лишеhttps://. Порожнє поле вимикає вебхуки. -
Натисніть «Згенерувати секрет» і збережіть «Секрет підпису» (
whsec_…) на своєму сервері. Ним ви перевіряєте, що запит надіслав Neocarts.

«Згенерувати новий секрет» вимикає старий одразу. Щоб змінити секрет без втрат, спершу покладіть новий на сервер, потім перегенеруйте.
Заголовки
Section titled “Заголовки”| Заголовок | Опис |
|---|---|
Content-Type |
application/json |
X-Neocarts-Event |
назва події, наприклад order.paid |
X-Neocarts-Delivery |
ідентифікатор доставки; той самий, що id у тілі |
X-Neocarts-Signature |
підпис: t=<unix-секунди>,v1=<hex> — див. Перевірка підпису |
| Поле | Тип | Опис |
|---|---|---|
id |
string | ідентифікатор доставки. Ключ ідемпотентності: повтор і ручне перевідправлення несуть той самий id |
event |
string | назва події — див. Події |
created_at |
string, ISO 8601 | коли подія сталася (а не коли надіслано цю спробу) |
shop_id |
string | ID магазину |
data |
object | знімок сутності на момент події плюс поля самої події — додаткові запити не потрібні |
{ "id": "019a0b7c-1f3e-7c1a-9c6e-0b9b1c2d3e4f", "event": "order.paid", "created_at": "2026-10-04T09:12:30+00:00", "shop_id": "7f3c2b1a-0d9e-4f8a-b7c6-d5e4f3a2b1c0", "data": { … }}Гроші — у копійках, дати — ISO 8601. Токенів карток і відповідей платіжного провайдера в даних немає.
Перевірка підпису
Section titled “Перевірка підпису”v1 = HMAC-SHA256(секрет, "<t>.<сире тіло запиту>") у hex.
- Візьміть тіло таким, яким воно прийшло — до парсингу JSON.
- Обчисліть HMAC і порівняйте з
v1за сталий час. - Відхиліть запит, якщо
tстаріший за 5 хвилин.
[$t, $v1] = sscanf($_SERVER['HTTP_X_NEOCARTS_SIGNATURE'], 't=%d,v1=%s');$body = file_get_contents('php://input');
$ok = abs(time() - $t) <= 300 && hash_equals(hash_hmac('sha256', "$t.$body", $secret), $v1);import crypto from 'node:crypto';
// rawBody — Buffer тіла до парсингу, напр. express.raw({ type: 'application/json' })function verify(rawBody, header, secret) { const { t, v1 } = Object.fromEntries(header.split(',').map((p) => p.split('='))); const expected = crypto.createHmac('sha256', secret).update(`${t}.`).update(rawBody).digest('hex'); return Math.abs(Date.now() / 1000 - Number(t)) <= 300 && v1.length === expected.length && crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));}Відповідь і повтори
Section titled “Відповідь і повтори”Відповідайте будь-яким 2xx протягом 10 секунд; тіло відповіді не читається. Усе інше — 4xx, 5xx, таймаут, відмова зʼєднання — невдала спроба, і Neocarts повторить запит:
| Спроба | Коли |
|---|---|
| 1 | одразу після події |
| 2 | через 1 хв |
| 3 | ще через 5 хв |
| 4 | ще через 15 хв |
| 5 | ще через 60 хв |
Після пʼятої невдалої спроби доставка стає failed. Повтор підписується заново (новий t) над тим самим тілом.
Журнал доставок — у панелі, «Магазин» → «Вебхуки»: подія, статус, спроби, HTTP-код, тіло запиту й ваша відповідь. Невдалу доставку можна «Надіслати повторно» — з тим самим id. Журнал зберігається 30 днів.
| Статус | Коли |
|---|---|
pending |
спроби ще тривають |
success |
ваш сервер відповів 2xx |
failed |
пʼять спроб невдалі, або URL прибрали до відправлення |
Що має робити ваш сервер
Section titled “Що має робити ваш сервер”- Відповідати одразу. Довгу обробку робіть після відповіді
2xx. - Бути ідемпотентним. Зберігайте оброблені
idі пропускайте повтори. - Не покладатися на порядок. Повтор старої події може прийти після новішої — обробляйте за
eventіdata. - Ігнорувати невідоме. Можуть зʼявитися нові значення
event— відповідайте на них2xx.
Знімки даних
Section titled “Знімки даних”data кожної події містить один зі знімків нижче. Поля самої події — на її сторінці.
Знімок замовлення
Section titled “Знімок замовлення”Для order.*. Позиції, контакти, доставка й підсумки мають ті самі форми, що в документі замовлення.
| Поле | Тип | Опис |
|---|---|---|
id |
string | ідентифікатор замовлення — той самий, що повертає POST /v1/shop/orders/create |
number |
string | номер для людей, YYMMDD-NNNNN |
status |
string | draft, pending_payment, paid, cancelled — Статуси |
source |
string | widget — оформив покупець у віджеті; subscription — продовження підписки |
locale |
string, може бути null | uk або en |
items |
array | позиції — як items[] |
discount_percent |
integer, може бути null | знижка на підписку |
contact |
object, може бути null | first_name, last_name, email, phone |
delivery |
object, може бути null | provider, type, data, recipient — форми delivery.data. Довідникові поля (city, branch, parcel_locker, street) мають вигляд { id, external_id, name }; external_id — ідентифікатор у перевізника (Ref Нової Пошти), з нього формуйте ТТН |
totals |
object | items_total, discount_total, total, копійки |
subscription_ids |
array of string | підписки замовлення; порожній до оплати |
created_at |
string, ISO 8601 | коли замовлення створено |
Знімок підписки
Section titled “Знімок підписки”Для subscription.*; однаковий для всіх цих подій.
| Поле | Тип | Опис |
|---|---|---|
id |
string | ідентифікатор підписки |
status |
string | active, paused, cancelled — статуси підписки |
status_reason |
string, може бути null | текст причини: коментар продавця або текст автоматичної паузи — причини паузи |
cancellation_reason |
string, може бути null | причина скасування; null, поки не скасовано |
product |
object, може бути null | id, external_id, title, variant |
quantity |
integer | одиниць на одне списання |
price |
integer, копійки | ціна однієї одиниці до знижки |
discount_percent |
integer, може бути null | знижка підписки, % |
interval_value |
integer, може бути null | інтервал списань, разом з interval_unit |
interval_unit |
string, може бути null | day або week — interval_unit |
next_charge_at |
string, може бути null | дата наступного списання, ISO 8601 |
paused_until |
string, може бути null | до якої дати пауза; null — без дати або не на паузі |
customer |
object, може бути null | id, first_name, last_name, email, phone, locale |
delivery |
object, може бути null | як у знімку замовлення |
card |
object, може бути null | brand, mask |
created_at |
string, ISO 8601 | коли підписка стартувала |
Знімок платежу
Section titled “Знімок платежу”Для payment.* і поля payment в order.paid.
| Поле | Тип | Опис |
|---|---|---|
id |
string | ідентифікатор платежу |
order_id |
string, може бути null | замовлення, яке оплачує платіж; null — перевірка картки під час її заміни |
provider |
string | plata-by-mono, liqpay, sandbox — провайдери |
status |
string | pending, success, failed, expired, refunded — статуси платежу |
amount |
integer, копійки | сума платежу |
refunded_amount |
integer, копійки | скільки вже повернено, разом |
card_mask |
string, може бути null | маска картки, напр. **** 4242 |
card_brand |
string, може бути null | бренд картки, напр. visa |
created_at |
string, ISO 8601 | коли платіж створено |
Які події йдуть за якими — у послідовності подій.
| Подія | Коли |
|---|---|
order.created |
замовлення оформлено й чекає оплати — ще не продаж |
order.paid |
замовлення оплачено або підтверджено вручну |
order.cancelled |
неоплачене замовлення закрито остаточно |
subscription.created |
підписка стартувала з оплаченого замовлення |
subscription.renewed |
продовження оплачено, next_charge_at зсунуто |
subscription.paused |
підписку поставлено на паузу |
subscription.resumed |
підписка знову активна |
subscription.cancelled |
підписку скасовано |
subscription.updated |
змінено кількість, графік, адресу або картку |
subscription.price_changed |
переоцінка товару змінила ціну підписки |
payment.failed |
списання за продовження не вдалося |
payment.refunded |
гроші повернено, повністю чи частково |