К содержанию
Libermall для разработчиков

Вебхуки

Вебхук — это запрос от Libermall к вашему серверу, когда с заказом что-то произошло. С ним не нужно постоянно опрашивать API. Подпись у всех событий одинаковая: HMAC-SHA256 по сырому телу запроса.
СобытиеКомуКогда
fulfillment.requestedПродавцуЗаказ на товар с выдачей на лету оплачен — выдайте товар. Подробно
order.fulfilledПартнёру Buyer APIКоды готовы
order.refundedПартнёру Buyer APIДеньги вернулись на кошелёк, причина — в data.reason

Подключить адрес

Продавцу — адрес выдачи задаётся в кабинете продавца. Партнёру — один HTTPS-адрес на аккаунт через API. Секрет для подписи придёт в ответе один раз; новый PUT выдаёт новый секрет.

curl -X PUT https://api.libermall.com/buyer-api/webhook \
  -H "x-buyer-api-key: $LIBERMALL_BUYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://ваш-сервер/libermall"}'

Посмотреть адрес — GET /buyer-api/webhook, остановить доставку — DELETE /buyer-api/webhook. Адрес должен быть публичным и по HTTPS. Перенаправления мы не выполняем: ответ 3xx считается неудачей.

Проверка подписи

Заголовок подписи: libermall-signature: t=<unix-секунды>, v1=<hex>, где

v1 = HMAC_SHA256(secret, "<t>.<сырое тело>")
  • Считайте подпись по сырому телу, до разбора JSON.
  • Сравнивайте в постоянное время (timingSafeEqual).
  • Отклоняйте событие, если t старше 5 минут.
import { createHmac, timingSafeEqual } from "node:crypto"

function verify(rawBody, header, secret) {
  const parts = Object.fromEntries(header.split(",").map((p) => p.trim().split("=")))
  if (Math.abs(Date.now() / 1000 - Number(parts.t)) > 300) return false
  const expected = createHmac("sha256", secret).update(`${parts.t}.${rawBody}`).digest()
  const got = Buffer.from(parts.v1 || "", "hex")
  return got.length === expected.length && timingSafeEqual(got, expected)
}

В Node.js то же самое делает verifyWebhookSignature из @libermall/shop-sdk.

Тело события

{
  "id": "evt_…",
  "type": "order.fulfilled",
  "created_at": "2026-10-29T12:00:00Z",
  "data": { "order_id": "order_…", "external_ref": "1042" }
}

Кодов в событиях нет — забирайте их запросом GET /buyer-api/orders/{id}.

Повторы и дубли

  • Отвечайте 2xx быстро, тяжёлую работу делайте после ответа.
  • Без 2xx мы повторяем доставку с нарастающей паузой, до 8 раз.
  • Одно событие может прийти дважды. Отсекайте дубли по id — он не меняется между повторами, как и заголовок x-libermall-idempotency-key.
  • Если вебхук не дошёл, опрос GET /buyer-api/orders/{id} работает всегда.