Overview
Neocarts sends a POST to the shop’s server whenever something happens to an order, a subscription or a payment. This is how the shop learns what it cannot see from its own side: a payment, a subscription renewal, a pause, a refund. There is no need to poll the Shop API.
How to turn them on
Section titled “How to turn them on”-
In the shop panel open Settings → Integration, section «Webhooks».
-
Enter the «Webhook URL» — the address Neocarts will
POSTto. Production acceptshttps://only. An empty field switches webhooks off. -
Press «Generate secret» and store the «Signing secret» (
whsec_…) on your server. You use it to check that a request came from Neocarts.

«Generate new secret» retires the old one at once. To rotate without losing events, put the new secret on the server first, then regenerate.
The request
Section titled “The request”Headers
Section titled “Headers”| Header | Description |
|---|---|
Content-Type |
application/json |
X-Neocarts-Event |
the event name, for example order.paid |
X-Neocarts-Delivery |
the delivery id; the same value as id in the body |
X-Neocarts-Signature |
the signature: t=<unix seconds>,v1=<hex> — see Verifying the signature |
| Field | Type | Description |
|---|---|---|
id |
string | the delivery id. The idempotency key: a retry and a manual resend carry the same id |
event |
string | the event name — see Events |
created_at |
string, ISO 8601 | when the event happened (not when this attempt was sent) |
shop_id |
string | the shop ID |
data |
object | the entity snapshot at the moment of the event plus the event’s own fields — no further calls needed |
{ "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": { … }}Money is in kopecks, dates are ISO 8601. The data never carries card tokens or payment-provider payloads.
Verifying the signature
Section titled “Verifying the signature”v1 = HMAC-SHA256(secret, "<t>.<raw request body>") in hex.
- Take the body exactly as it arrived — before JSON parsing.
- Compute the HMAC and compare it with
v1in constant time. - Reject the request if
tis older than 5 minutes.
[$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 — the body Buffer before parsing, e.g. 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));}Response and retries
Section titled “Response and retries”Answer with any 2xx within 10 seconds; the response body is not read. Anything else — a 4xx, a 5xx, a timeout, a refused connection — is a failed attempt, and Neocarts retries:
| Attempt | When |
|---|---|
| 1 | right after the event |
| 2 | after 1 min |
| 3 | 5 min later |
| 4 | 15 min later |
| 5 | 60 min later |
After the fifth failed attempt the delivery becomes failed. A retry is signed afresh (a new t) over the same body.
The delivery log is in the panel, «Shop» → «Webhooks»: event, status, attempts, HTTP status, the request body and your response. A failed delivery can be resent («Resend») with the same id. The log is kept for 30 days.
| Status | When |
|---|---|
pending |
attempts still running |
success |
your server answered 2xx |
failed |
five attempts failed, or the URL was removed before the send |
What your server must do
Section titled “What your server must do”- Answer first. Do long work after returning
2xx. - Be idempotent. Store the processed
ids and skip repeats. - Not rely on order. A retry of an older event can land after a newer one — handle by
eventanddata. - Ignore the unknown. New
eventvalues may appear — answer them with2xx.
Data snapshots
Section titled “Data snapshots”Every event’s data holds one of the snapshots below. The event’s own fields are on its page.
Order snapshot
Section titled “Order snapshot”For order.*. Lines, contact, delivery and totals have the same shapes as in the order document.
| Field | Type | Description |
|---|---|---|
id |
string | the order id — the same value POST /v1/shop/orders/create returned |
number |
string | the number for people, YYMMDD-NNNNN |
status |
string | draft, pending_payment, paid, cancelled — Statuses |
source |
string | widget — placed by the shopper in the widget; subscription — a subscription renewal |
locale |
string, nullable | uk or en |
items |
array | the lines — as items[] |
discount_percent |
integer, nullable | the subscription discount |
contact |
object, nullable | first_name, last_name, email, phone |
delivery |
object, nullable | provider, type, data, recipient — delivery.data shapes. Directory fields (city, branch, parcel_locker, street) look like { id, external_id, name }; external_id is the carrier’s own reference (Nova Poshta Ref) — make the waybill from it |
totals |
object | items_total, discount_total, total, kopecks |
subscription_ids |
array of string | the order’s subscriptions; empty until it is paid |
created_at |
string, ISO 8601 | when the order was created |
Subscription snapshot
Section titled “Subscription snapshot”For subscription.*; the same for all of them.
| Field | Type | Description |
|---|---|---|
id |
string | the subscription id |
status |
string | active, paused, cancelled — subscription statuses |
status_reason |
string, nullable | the reason text: the merchant’s comment or the text of an automatic pause — pause reasons |
cancellation_reason |
string, nullable | cancellation reason; null until cancelled |
product |
object, nullable | id, external_id, title, variant |
quantity |
integer | units per charge |
price |
integer, kopecks | price of one unit before discount |
discount_percent |
integer, nullable | the subscription discount, % |
interval_value |
integer, nullable | the charge interval, with interval_unit |
interval_unit |
string, nullable | day or week — interval_unit |
next_charge_at |
string, nullable | date of the next charge, ISO 8601 |
paused_until |
string, nullable | until when the pause lasts; null — open-ended or not paused |
customer |
object, nullable | id, first_name, last_name, email, phone, locale |
delivery |
object, nullable | as in the order snapshot |
card |
object, nullable | brand, mask |
created_at |
string, ISO 8601 | when the subscription started |
Payment snapshot
Section titled “Payment snapshot”For payment.* and the payment field of order.paid.
| Field | Type | Description |
|---|---|---|
id |
string | the payment id |
order_id |
string, nullable | the order the payment pays for; null — a card check during a card replacement |
provider |
string | plata-by-mono, liqpay, sandbox — providers |
status |
string | pending, success, failed, expired, refunded — payment statuses |
amount |
integer, kopecks | the payment amount |
refunded_amount |
integer, kopecks | how much has been refunded, in total |
card_mask |
string, nullable | the card mask, e.g. **** 4242 |
card_brand |
string, nullable | the card brand, e.g. visa |
created_at |
string, ISO 8601 | when the payment was created |
Events
Section titled “Events”Which events follow which is in the event flow.
| Event | When |
|---|---|
order.created |
an order was placed and awaits payment — not a sale yet |
order.paid |
an order was paid or confirmed by hand |
order.cancelled |
an unpaid order was closed for good |
subscription.created |
a subscription started from a paid order |
subscription.renewed |
a renewal was paid, next_charge_at moved |
subscription.paused |
a subscription was paused |
subscription.resumed |
a subscription is active again |
subscription.cancelled |
a subscription was cancelled |
subscription.updated |
quantity, schedule, address or card changed |
subscription.price_changed |
a product reprice changed the subscription’s price |
payment.failed |
a renewal charge failed |
payment.refunded |
money went back, in full or in part |