Вебхуки

Вебхук — это HTTP-запрос от площадки на ваш адрес в момент события. Кабинет → Настройки → Вебхуки.

Вебхуки входят в тариф «Рост» и выше (Тариф продавца и оплата подписки). На младшем тарифе раздел открыт только для чтения: прежние записи видны и их можно удалить, но новые не заводятся и события не отправляются.

Настройка

• URL — адрес, который принимает POST с JSON.
• События:
  • order.created — новый заказ; приходит продавцу (покупатель этот заказ и так оформил сам);
  • order.status_changed — заказ сменил статус; приходит обеим сторонам сделки;
  • stock.changed — изменился остаток товара; приходит владельцу товара.
• Активен — включает и отключает отправку.

Что в теле запроса

Тело — короткая карточка сделки: order (id, номер, статус, суммы, число позиций, даты), seller и buyer (id, название, ИНН), а также side — кем вашей компании приходится этот заказ (seller или buyer). У order.status_changed дополнительно есть from, to, comment и changed_by — кто сменил статус: по нему легко отличить своё действие от действия второй стороны.

Позиции заказа, реквизиты доставки и контакты в теле не передаются — заберите их по order.id через API (REST API и токены). Так вебхук остаётся лёгким, а данные — всегда актуальными.

При создании показывается секрет — он виден один раз. Каждый запрос подписывается им: заголовок X-Kup2b-Signature содержит HMAC-SHA256 от тела запроса. Проверяйте подпись, прежде чем доверять данным. Дополнительно приходят X-Kup2b-Event (событие) и X-Kup2b-Delivery (идентификатор доставки — по нему удобно отбрасывать повторы).

В теле есть и event_id — идентификатор самого события сделки. Площадка доводит событие до доставки даже после сбоя у себя (очередь, перезапуск), и в редком случае одно событие может прийти повторно: у повтора event_id тот же — запоминайте обработанные и пропускайте их. У stock.changed события сделки нет — event_id там пустой (null).

Доставка и повторы

Ваш обработчик должен ответить кодом 2xx. Если ответа нет или код другой, площадка повторит попытку до пяти раз с нарастающими паузами (1, 5, 25 и 125 минут). Журнал доставок — на той же странице: событие, код ответа, число попыток, время. Кнопка «Тест» отправляет пробное событие.

Отвечайте быстро: тяжёлую обработку ставьте в свою очередь, а на вебхук возвращайте 200 сразу. Для выборки данных по событию используйте API (REST API и токены).