Вебхуки
Вебхук — это запрос от 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}работает всегда.