События
| Событие | Когда происходит |
|---|---|
order.created | Появился заказ из любого канала продаж. |
order.updated | Заказ изменился: позиции, доставка, оплата или статус. |
order.status_changed | Заказ перешёл в другой статус; previous_attributes.status — статус до перехода. |
order.paid | Заказ стал оплаченным или создан сразу оплаченным. |
order.cancelled | Заказ отменён. |
payment.created | Появился платёж по заказу: счёт, ожидающий денег, или уже полученные деньги. |
payment.succeeded | Деньги по платежу получены, в том числе у платежа, созданного сразу полученным, как наличные на кассе. |
payment.status_changed | Платёж перешёл в другой статус; previous_attributes.status — статус до перехода. |
payment.updated | Платёж изменился: статус, суммы, возвраты по нему. |
refund.created | По заказу сделан возврат. |
refund.completed | Деньги по возврату выплачены, в том числе у возврата, выполненного сразу. |
refund.status_changed | Возврат перешёл в другой статус; previous_attributes.status — статус до перехода. |
refund.updated | Возврат изменился: статус или проводки по платежам. |
fiscal_document.created | Заведён фискальный документ: фактура, кредит- или дебет-нота. |
fiscal_document.updated | Фискальный документ изменился. |
fiscal_document.issued | Налоговая выпустила документ: у него есть номер, учётная дата и налог. |
fiscal_document.failed | Выпуск не удался: сбой или отказ налоговой; previous_attributes.status — статус до этого. |
fiscal_document.annulled | Фактура снята аннулирующей нотой и для продажи больше не действует. |
tax_period.status_changed | Налоговый период закрыт или открыт снова; previous_attributes.status — статус до смены. |
money_transaction.created | Проведено движение денег: приход или расход по счёту. |
money_transaction.updated | Движение денег изменилось: статья, комментарий, сумма или дата. |
money_transaction.deleted | Движение денег стёрто: ручная запись удалена или проводка снята вместе со своим документом. |
pos_shift.opened | Открыта кассовая смена. |
pos_shift.closed | Смена закрыта: ящик пересчитан, расхождение проведено в журнал денег. |
pos_shift.updated | Смена изменилась, в том числе пересверка закрытой смены поздним движением ящика. |
pos_cash_movement.created | В журнал денежного ящика записано движение: продажа или возврат налом, внесение, выдача, сдача в сейф, сторно. |
gift_card.created | Выпущена подарочная карта: продажей или без неё (компенсация, промо). Долгом она становится после оплаты — смотрите outstanding. |
gift_card.updated | Подарочная карта изменилась: остаток, состояние, срок или владелец. Активация после оплаты приходит этим событием. |
gift_card_transaction.created | В журнал подарочной карты записана строка: выпуск, погашение, возврат на карту, корректировка, аннулирование, блокировка или перенос остатка. |
customer_account.created | Открыт счёт покупателя в книге долгов: лимит, срок оплаты и статус. |
customer_account.updated | Счёт покупателя изменился: остаток после каждой записи журнала, лимит, срок, приостановка или переход к другому покупателю. |
customer_account_entry.created | В книгу долгов покупателя записана строка: продажа в долг, погашение, возврат, списание, взаимозачёт, удержание или сторно. |
customer_account_entry.updated | Запись книги долгов перенесена на счёт оставшегося покупателя при слиянии покупателей или потеряла справку об удержании: справку сняли из реестра удержаний, tax_withholding_id стал null. Сумма записи не меняется. |
supplier.created | Заведён поставщик: реквизиты и условия расчётов. |
supplier.updated | Поставщик изменился: реквизиты, условия расчётов, активность или связь с покупателем-двойником. |
supplier.deleted | Поставщик стёрт: стереть можно только поставщика без документов. |
supplier_bill.created | Заведён счёт поставщика: черновик или сразу проведённый документ (долг по поставке, счёт по акту реализации). |
supplier_bill.updated | Счёт поставщика изменился: правка черновика, проведение, одобрение к оплате, сверка с приёмкой или аннулирование. |
supplier_bill.posted | Счёт поставщика проведён: с этого момента он в кредиторке и книге покупок. Приходит и для документа, заведённого сразу проведённым. |
supplier_bill.voided | Счёт поставщика аннулирован: из кредиторки и книги покупок он выходит, его оплаты сняты. |
supplier_bill.deleted | Черновик счёта поставщика стёрт. Проведённый документ не стирается, а аннулируется. |
supplier_bill_payment.created | Счёт поставщика оплачен: деньгами, зачётом, нотой кредита, авансом по заказу, расходом журнала или вне системы. |
supplier_bill_payment.updated | Оплата счёта поставщика изменилась: расход журнала перераспределили между счетами. |
supplier_bill_payment.deleted | Оплата счёта поставщика снята: отменена, сторнирована вместе с зачётом или с аннулированием счёта. |
settlement_agreement.created | Заведено соглашение о взаимозачёте с поставщиком и покупателем. |
settlement_agreement.updated | Соглашение о взаимозачёте изменилось: реквизиты, срок, расписание или дата следующего зачёта. |
settlement_agreement.deleted | Соглашение о взаимозачёте удалено: по нему не было ни одного зачёта. |
settlement_offset.created | Проведён взаимозачёт: долг покупателя закрыт встречным долгом магазина перед поставщиком. |
settlement_offset.updated | Взаимозачёт изменился: аннулирован или покупатель стороны удалён. |
settlement_offset.voided | Взаимозачёт аннулирован: его погашения сняты, долги снова открыты. |
purchase_order.created | Заказ поставщику создан черновиком. |
purchase_order.updated | Заказ поставщику изменён: строки, ответ поставщика, принятое по нему или ожидаемая поставка. |
purchase_order.status_changed | Заказ поставщику перешёл в другой статус: размещён, принят частично или полностью, закрыт или отменён; previous_attributes.status — статус до перехода. |
purchase_order.deleted | Черновик заказа поставщику стёрт. Размещённый заказ не стирается, а отменяется. |
goods_receipt.created | Товар принят от поставщика: приёмка проведена, остаток и себестоимость обновлены. |
goods_receipt.updated | Приёмка изменена: корректировка количеств или цен либо реквизиты накладной. |
goods_receipt.voided | Приёмка сторнирована: товар снят с остатка, долг по поставке аннулирован. |
supplier_return.created | Возврат поставщику создан черновиком. |
supplier_return.updated | Возврат поставщику изменён: строки, корректировка или полученная компенсация. |
supplier_return.status_changed | Возврат поставщику перешёл в другой статус: отгружен, закрыт или аннулирован; previous_attributes.status — статус до перехода. |
supplier_return.deleted | Черновик возврата поставщику стёрт. Отгруженный возврат не стирается, а аннулируется. |
consignment_settlement.created | Акт реализации создан черновиком: продажи периода собраны для сверки с поставщиком. |
consignment_settlement.updated | Акт реализации изменился: период или заметка, строки пересобраны после корректировки приёмки, по акту выставлен или снят счёт. |
consignment_settlement.posted | Акт реализации проведён: продажи периода закреплены за ним, по нему поставщик выставляет фактуру. |
consignment_settlement.voided | Акт реализации аннулирован: его продажи войдут в следующий акт. Акт не стирается, а аннулируется. |
tax_withholding.created | В реестре удержаний новая запись: налог удержали у магазина (провайдер расчёта, банк, покупатель-агент) или удержал магазин при оплате поставщику — направление в direction. |
tax_withholding.updated | Запись реестра удержаний изменилась: провайдер уточнил сумму расчёта, сменился источник или юрлицо. |
tax_withholding.annulled | Магазин аннулировал свой сертификат удержания: сумма больше не к перечислению, номер остаётся занятым. Приходит вместе с tax_withholding.updated. |
tax_withholding.deleted | Запись удалена из реестра удержаний: ручной ввод, удержание, снятое сторно провайдера, или справка погашения при сторно записи книги долгов. |
product.created | В каталоге появился товар. |
product.updated | Товар изменился. |
product.deleted | Товар ушёл в архив или стёрт. |
inventory_level.updated | Остаток варианта на точке изменился или появился. |
stock_movement.created | В журнал склада записано движение: продажа, приёмка, списание, ревизия, перемещение или сторно. |
stock_movement.updated | У движения склада изменилось то, что отдаёт лента: обнулилась ссылка на удалённый документ, перенесён заказ, пересчитано количество при смене единицы. |
lot.created | Заведена партия товара. |
lot.updated | Партия изменилась: статус доступности, слияние, номер или срок годности. |
lot.deleted | Снята партия, заведённая ревизией и ни к чему не привязанная. |
location_transfer.created | Проведено перемещение товара между точками. |
location_transfer.updated | Строки перемещения переписаны: перевод единицы учёта или слияние партий. |
stocktake.created | Начата ревизия остатков точки. |
stocktake.status_changed | Ревизия сменила статус: передана на проведение, проведена, отменена или вернулась в черновик после сбоя. Прежний статус — в previous_attributes. |
stocktake.updated | Ревизия изменилась. Строки читаются лентой /v1/stocktake-lines — у них своих событий нет. |
customer.created | Появился покупатель. |
customer.updated | Покупатель изменился — в том числе его группы (group_ids). |
customer.deleted | Покупатель удалён. |
customer_group.created | Появилась группа покупателей. |
customer_group.updated | Группа покупателей изменилась: имя, описание или активность. Смена состава приходит событием customer.updated покупателя. |
customer_group.deleted | Группа покупателей удалена; её участники приходят событием customer.updated. |
price_list.created | Появился прайс-лист: лист точки или оптовый. Оптовый приходит только приложению с доступом к себестоимости. |
price_list.updated | Прайс-лист изменился: правило, округление, ручная цена или надбавка. Сами цены — в лентах price-list-items и price-list-modifier-items. |
price_list.deleted | Прайс-лист удалён вместе с его ручными ценами и надбавками. |
bulk_operation.finished | Закончилась массовая операция этого приложения; приходит только ему. |
Запись, изменённая несколько раз в одной транзакции, даёт одно событие. Те же события лежат в ленте событий 30 дней: читайте её, чтобы догнать пропущенное, пока ваш адрес не отвечал.
Добавьте адрес
Создайте адрес с URL и нужными событиями. Адрес — https на публичном хосте; каждому событию нужен scope чтения его ресурса, orders:read для order.*. У приложения может быть до 10 адресов. То же магазин может сделать в карточке приложения, на вкладке «Вебхуки».
curl -X POST "https://api.saleya.app/v1/webhook-endpoints" \
-H "Authorization: Bearer $SALEYA_API_TOKEN" \
-H 'Idempotency-Key: 6f5e4d3c-2b1a-4098-8f7e-6d5c4b3a2918' \
-H "Content-Type: application/json" \
-d '{
"url": "https://erp.example.com/saleya/webhooks",
"description": "ERP",
"enabled_events": [
"order.created",
"order.paid",
"inventory_level.updated"
]
}'Затем получите секрет подписи и храните его рядом с токеном:
curl "https://api.saleya.app/v1/webhook-endpoints/14/secret" \
-H "Authorization: Bearer $SALEYA_API_TOKEN"HTTP/1.1 200 OK
{
"endpoint_id": 14,
"secret": "whsec_c2FsZXlhLWd1aWRlLXNhbXBsZS1zZWNyZXQtMDAzMiE="
}Доставка
Доставка — POST с событием в теле, тем же объектом, что в ленте событий, и тремя заголовками: webhook-id — ID события; webhook-timestamp — момент попытки; webhook-signature — подпись.
POST /saleya/webhooks HTTP/1.1
Host: erp.example.com
Content-Type: application/json
webhook-id: 4518
webhook-timestamp: 1794407400
webhook-signature: v1,70uXS7tBMWQWQJP0MhHc6+QvfBJlYQY9zlbIvyYLm28=
{
"id": 4518,
"type": "inventory_level.updated",
"created_at": "2026-11-11T14:30:00Z",
"actor": {
"type": "operator",
"id": null
},
"request_id": null,
"data": {
"id": 90211,
"object": {
"variant_id": 1042,
"location_id": 3,
"on_hand": "18",
"reserved": "2",
"available": "16",
"updated_at": "2026-11-11T14:30:00Z"
},
"previous_attributes": null
}
}data.object — запись такой, какой она была при первой отправке доставки, с полями, которые разрешают scopes приложения; у стёртой записи — null. Ответьте любым 2xx за 10 секунд; любой другой ответ, редирект или отсутствие ответа — неудача.
Проверка подписи
Подпись — v1, и HMAC-SHA256 в base64 от {webhook-id}.{webhook-timestamp}.{body} на секрете — base64-части после whsec_. Проверяйте её до разбора тела:
<?php
/**
* Checks a Saleya webhook delivery signed by the Standard Webhooks scheme.
*
* $payload — the raw request body, exactly as received.
* $headers — the request headers with lowercase names.
* $secret — the signing secret of the endpoint, whsec_...
*
* Returns the decoded event or throws when the headers, the time or the signature do not match.
*/
function verify_saleya_webhook(string $payload, array $headers, string $secret, int $toleranceSeconds = 300, ?int $now = null): array
{
$id = $headers['webhook-id'] ?? '';
$timestamp = $headers['webhook-timestamp'] ?? '';
$signatures = $headers['webhook-signature'] ?? '';
if ($id === '' || !ctype_digit($timestamp) || $signatures === '') {
throw new RuntimeException('Missing webhook headers');
}
if (abs(($now ?? time()) - (int) $timestamp) > $toleranceSeconds) {
throw new RuntimeException('Webhook timestamp is outside the tolerance');
}
$key = str_starts_with($secret, 'whsec_') ? base64_decode(substr($secret, 6), true) : false;
if ($key === false) {
throw new InvalidArgumentException('The secret must start with whsec_');
}
$expected = base64_encode(hash_hmac('sha256', "{$id}.{$timestamp}.{$payload}", $key, true));
foreach (explode(' ', $signatures) as $versioned) {
[$version, $signature] = array_pad(explode(',', $versioned, 2), 2, '');
if ($version === 'v1' && hash_equals($expected, $signature)) {
return json_decode($payload, true, 512, JSON_THROW_ON_ERROR);
}
}
throw new RuntimeException('Invalid webhook signature');
}
- Подписывайте тело ровно таким, каким оно пришло: разбор и повторная сериализация JSON меняют байты.
- После ротации в заголовке две подписи через пробел: доставка верна, если совпала одна из них.
- Отклоняйте старый
webhook-timestamp, чтобы перехваченную доставку нельзя было прислать позже. - Сравнивайте за постоянное время, как в примерах.
Вместо этих функций подойдёт любая библиотека Standard Webhooks с тем же секретом.
Повторы и неудачи
Неудачная доставка повторяется до 10 раз с растущими паузами, примерно 72 часа. Если у адреса нет ни одного успеха 72 часа, он выключается, а владелец магазина получает письмо. Выключенному адресу новые события не отправляются: после включения догоните пропущенное по ленте событий — она хранит их 30 дней.
- Журнал доставок адреса показывает, что ушло, что ждёт и что не доставлено, с ответами вашего сервера.
- Повторите доставку после исправления на своей стороне, не дожидаясь следующей попытки.
- Отправьте тестовое событие,
ping, чтобы проверить адрес. - Смените секрет: новый подписывает сразу, прежний подписывает ещё 24 часа.
Дубли и порядок
Доставка может прийти больше одного раза — например, когда ваш сервер ответил после таймаута, — а доставки разных событий могут прийти не по порядку. Запоминайте webhook-id обработанных доставок и перед перезаписью записи сравнивайте её updated_at со своей копией.
Отвечайте быстро, а работу делайте в очереди. Считайте вебхук сигналом, а синхронизацию по курсору — источником правды.