Skip to content

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.

  1. In the shop panel open Settings → Integration, section «Webhooks».

  2. Enter the «Webhook URL» — the address Neocarts will POST to. Production accepts https:// only. An empty field switches webhooks off.

  3. Press «Generate secret» and store the «Signing secret» (whsec_…) on your server. You use it to check that a request came from Neocarts.

The «Integration» tab: shop ID, API key, webhook URL and signing secret

«Generate new secret» retires the old one at once. To rotate without losing events, put the new secret on the server first, then regenerate.

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.

v1 = HMAC-SHA256(secret, "<t>.<raw request body>") in hex.

  1. Take the body exactly as it arrived — before JSON parsing.
  2. Compute the HMAC and compare it with v1 in constant time.
  3. Reject the request if t is 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);

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
  • 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 event and data.
  • Ignore the unknown. New event values may appear — answer them with 2xx.

Every event’s data holds one of the snapshots below. The event’s own fields are on its page.

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

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

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

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