Перейти до вмісту

Огляд

Neocarts надсилає POST на сервер магазину щоразу, коли щось сталося із замовленням, підпискою чи платежем. Так магазин дізнається про те, чого не бачить зі свого боку: оплату, продовження підписки, паузу, повернення грошей. Опитувати Shop API не потрібно.

  1. Відкрийте в панелі магазину Налаштування → Інтеграція, розділ «Вебхуки».

  2. Вкажіть «URL для вебхуків» — адресу, на яку Neocarts надсилатиме POST. У продакшені — лише https://. Порожнє поле вимикає вебхуки.

  3. Натисніть «Згенерувати секрет» і збережіть «Секрет підпису» (whsec_…) на своєму сервері. Ним ви перевіряєте, що запит надіслав Neocarts.

Вкладка «Інтеграція»: ID магазину, API-ключ, URL для вебхуків і секрет підпису

«Згенерувати новий секрет» вимикає старий одразу. Щоб змінити секрет без втрат, спершу покладіть новий на сервер, потім перегенеруйте.

Заголовок Опис
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. Токенів карток і відповідей платіжного провайдера в даних немає.

v1 = HMAC-SHA256(секрет, "<t>.<сире тіло запиту>") у hex.

  1. Візьміть тіло таким, яким воно прийшло — до парсингу JSON.
  2. Обчисліть HMAC і порівняйте з v1 за сталий час.
  3. Відхиліть запит, якщо 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);

Відповідайте будь-яким 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.

data кожної події містить один зі знімків нижче. Поля самої події — на її сторінці.

Для 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 коли замовлення створено

Для 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 коли підписка стартувала

Для 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 гроші повернено, повністю чи частково