Вебхуки

Вебхук сообщает вашей системе, что в магазине что-то изменилось, через мгновение после изменения. Доставки подписаны по схеме Standard Webhooks, поэтому их проверяет любая её библиотека.

Загружаем поисковый индекс…

Вебхуки

События

СобытиеКогда происходит
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
<?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 дней.

Дубли и порядок

Доставка может прийти больше одного раза — например, когда ваш сервер ответил после таймаута, — а доставки разных событий могут прийти не по порядку. Запоминайте webhook-id обработанных доставок и перед перезаписью записи сравнивайте её updated_at со своей копией.

Отвечайте быстро, а работу делайте в очереди. Считайте вебхук сигналом, а синхронизацию по курсору — источником правды.

Следующий гайдБухгалтерия через API