Настройка вебхуков

Новость на модерации

Обновлено

18.12.2025

Содержание статьи

Нотификации (webhooks) — это POST-запросы, которые Lamoda отправляет на ваш URL при изменении статуса заказа или товара. 
 
<h2>Чек-лист подключения</h2> 
 
<table style="border-collapse: collapse; width: 100%;"> 
<tbody> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">№</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Действие</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Кто делает</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">1</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Реализовать endpoint для приёма POST-запросов</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Вы</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">2</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Предоставить URL для получения нотификаций</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Вы → KAM</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">3</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Добавить IP Lamoda в whitelist (получить у KAM)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Вы</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">4</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Предоставить логин/пароль для Basic Auth (опционально)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Вы → KAM</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">5</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Настроить отправку нотификаций</td> 
<td style="border: 1px solid #ddd; padding: 8px;">KAM</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">6</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Протестировать на Demo-окружении</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Вы</td> 
</tr> 
</tbody> 
</table> 
 
<h2>Требования к endpoint</h2> 
 
<h3>URL</h3> 
 
Ваш endpoint должен: 
<ul> 
<li>Принимать POST-запросы</li> 
<li>Быть доступен 24/7</li> 
<li>Работать по HTTPS</li> 
<li>Отвечать быстро (желательно < 5 сек)</li> 
</ul> 
 
<h3>Коды ответа</h3> 
 
<table style="border-collapse: collapse; width: 100%;"> 
<tbody> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">Код</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Поведение Lamoda</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>2xx</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;"> Нотификация успешно доставлена</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>3xx</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">↪ Редирект (максимум 5 редиректов)</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>4xx</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;"> Ошибка, повторная отправка НЕ будет</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>5xx</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;"> Повторная отправка по алгоритму</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">Timeout</td> 
<td style="border: 1px solid #ddd; padding: 8px;"> Повторная отправка по алгоритму</td> 
</tr> 
</tbody> 
</table> 
 
<h3>Алгоритм повторной отправки</h3> 
 
При ошибке 5xx или timeout Lamoda повторяет отправку с увеличивающимся интервалом: 
 
<table style="border-collapse: collapse; width: 100%;"> 
<tbody> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">Попытка</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Интервал</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Пример времени</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">1</td> 
<td style="border: 1px solid #ddd; padding: 8px;">—</td> 
<td style="border: 1px solid #ddd; padding: 8px;">10:00:00</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">2</td> 
<td style="border: 1px solid #ddd; padding: 8px;">80 сек</td> 
<td style="border: 1px solid #ddd; padding: 8px;">10:01:20</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">3</td> 
<td style="border: 1px solid #ddd; padding: 8px;">240 сек (80×3)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">10:05:20</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">4</td> 
<td style="border: 1px solid #ddd; padding: 8px;">720 сек (80×3×3)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">10:17:20</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">5</td> 
<td style="border: 1px solid #ddd; padding: 8px;">2160 сек (80×3×3×3)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">10:53:20</td> 
</tr> 
</tbody> 
</table> 
 
Формула: <code>80 × 3^(N-1)</code> секунд, где N — номер попытки. Максимум 5 попыток. 
 
 После 5 неудачных попыток нотификация теряется! 
Обеспечьте высокую доступность вашего endpoint. Если нотификации были потеряны, используйте метод переотправки. 
<h2>Типы нотификаций</h2> 
 
<table style="border-collapse: collapse; width: 100%;"> 
<tbody> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">Тип (<code>type</code>)</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Описание</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>statusChanged</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Изменился статус заказа</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>itemStatusChanged</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Изменился статус товара в заказе</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>fulfilmentShipmentStatusChanged</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Изменился статус FBO-поставки</td> 
</tr> 
</tbody> 
</table> 
 
<h2>Пример нотификации</h2> 
 
<pre><code>{ 
 "type": "statusChanged", 
 "trackingId": "117391950", 
 "data": { 
 "id": "CZ117391950", 
 "status": "Delivered", 
 "paymentMethod": "COD", 
 "fullSum": "12000", 
 "deliveryPrice": "250.00", 
 "createdAt": "2025-12-01", 
 "updatedAt": "2025-12-03 17:48:00", 
 "currency": "rub", 
 "items": [ 
 { 
 "id": 7598, 
 "status": "Delivered", 
 "sku": "SELLER-SKU-001", 
 "paidPrice": 12000, 
 "size": "42", 
 "datamatrix": null 
 } 
 ], 
 "shippingAddress": { 
 "city": "Москва", 
 "street": "Летниковская", 
 "houseNum": "д.2 с1", 
 "apartment": "909" 
 }, 
 "deliveryMethod": { 
 "deliveryDate": "2025-12-03", 
 "deliveryIntervalFrom": "15:00", 
 "deliveryIntervalTo": "18:00", 
 "shippingMethodName": "Курьерская доставка Lamoda Express" 
 }, 
 "customer": { 
 "firstName": "Иван", 
 "lastName": "Петров", 
 "phone": "+79001234567" 
 } 
 }, 
 "date": "2025-12-03 17:48:00", 
 "sequenceNumber": 5 
}</code></pre> 
 
<h2>Пример обработчика (Python)</h2> 
 
<pre><code>from flask import Flask, request, jsonify 
 
app = Flask(__name__) 
 
@app.route('/lamoda/webhook', methods=['POST']) 
def handle_webhook(): 
 data = request.json 
 
 notification_type = data.get('type') 
 order_id = data['data']['id'] 
 status = data['data']['status'] 
 
 print(f"Received: {notification_type}, Order: {order_id}, Status: {status}") 
 
 # Обработка по типу нотификации 
 if notification_type == 'statusChanged': 
 process_order_status(data['data']) 
 elif notification_type == 'itemStatusChanged': 
 process_item_status(data['data']) 
 
 # Важно: вернуть 200 быстро! 
 return jsonify({"status": "ok"}), 200 
 
def process_order_status(order_data): 
 # Ваша бизнес-логика 
 pass 
 
def process_item_status(order_data): 
 # Ваша бизнес-логика 
pass</code></pre> 
 
<h2>Переотправка нотификаций</h2> 
 
Если вы пропустили нотификации, можно запросить их повторно: 
 
<pre><code><a href="<a class="txttohtmllink" href="https://academy.lamoda.ru/articles/api/apispec/lamoda-b2b-platform-api/#/%;D0%A3%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F/post_api_1_resend_order_notifications">https://academy.lamoda.ru/articles/api/apispec/lamoda-b2b-platform-api/#/%;D0%A3%D0%B2%D0%B5%D0%B4%D0%BE%D0%BC%D0%BB%D0%B5%D0%BD%D0%B8%D1%8F/post_api_1_resend_order_notifications</a>" target="_blank">POST /api/v1/notifications/resend</a> 
 
{ 
 "trackingIds": ["CZ117391950", "CZ117391951", "CZ117391952"] 
}</code></pre> 
 
 Ограничения переотправки 
<ul> 
<li>Максимум 100 заказов в одном запросе</li> 
<li>Один заказ можно запросить не чаще 1 раза в 15 минут</li> 
<li>Переотправляются ВСЕ нотификации по заказу</li> 
</ul> 
<h2>Тестирование на Demo</h2> 
 
На Demo-окружении можно протестировать получение нотификаций по сценариям: 
 
<pre><code>POST /api/v1/orders/{orderNr}/status 
 
{ 
 "scenario": "delivered" 
}</code></pre> 
 
<h3>Доступные сценарии</h3> 
 
<table style="border-collapse: collapse; width: 100%;"> 
<tbody> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;">Сценарий</td> 
<td style="border: 1px solid #ddd; padding: 8px;">Описание</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>delivered</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Заказ доставлен клиенту</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>notDelivered</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Адрес вне зоны доставки</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>notBought</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Клиент отказался от товара</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>partialBought</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Частичный выкуп (1 из 2 товаров)</td> 
</tr> 
<tr> 
<td style="border: 1px solid #ddd; padding: 8px;"><code>postponed</code></td> 
<td style="border: 1px solid #ddd; padding: 8px;">Доставка перенесена</td> 
</tr> 
</tbody> 
</table> 
 
<h2>Best Practices</h2> 
 
 Рекомендации 
<ul> 
<li>Отвечайте быстро — вернуть 200 и обработать асинхронно</li> 
<li>Идемпотентность — обрабатывайте дубли корректно (по sequenceNumber)</li> 
<li>Не валидируйте количество полей — новые поля могут добавляться</li> 
<li>Логируйте всё — тело запроса, время, результат обработки</li> 
<li>Мониторинг — отслеживайте количество ошибок</li> 
</ul> 
<h2>Обратная совместимость</h2> 
 
Lamoda гарантирует: 
<ul> 
<li>Существующие поля не удаляются</li> 
<li>Тип существующих полей не изменяется</li> 
<li>Новые поля могут добавляться</li> 
</ul> 
 
 Не делайте strict validation по полям! 
Не отклоняйте нотификацию, если в ней появилось новое поле. Игнорируйте неизвестные поля. 
<h2>См. также</h2> 
 
<ul> 
<li><a href="6_4_order_statuses.html">Статусы заказов</a></li> 
<li><a href="10_2_notification_types.html">Типы нотификаций (подробно)</a></li> 
<li><a href="17_2_error_codes.html">Коды ошибок</a></li> 
</ul>

Помогла эта информация?

Да Нет

Спасибо за отзыв

Отправить

Типы уведомлений

Рекомендации по FBO в API