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

Нотификации (webhooks) — это POST-запросы, которые Lamoda отправляет на ваш URL при изменении статуса заказа или товара.

Чек-лист подключения

Требования к endpoint

URL

Ваш endpoint должен:

• Принимать POST-запросы
• Быть доступен 24/7
• Работать по HTTPS
• Отвечать быстро (желательно < 5 сек)

Коды ответа

Алгоритм повторной отправки

При ошибке 5xx или timeout Lamoda повторяет отправку с увеличивающимся интервалом:

Формула: 80 × 3^(N-1) секунд, где N — номер попытки. Максимум 5 попыток.

Типы нотификаций

Пример нотификации

{
  "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
}

Пример обработчика (Python)

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

Переотправка нотификаций

Если вы пропустили нотификации, можно запросить их повторно:

POST /api/v1/notifications/resend

{
  "trackingIds": ["CZ117391950", "CZ117391951", "CZ117391952"]
}

Ограничения переотправки

• Максимум 100 заказов в одном запросе
• Один заказ можно запросить не чаще 1 раза в 15 минут
• Переотправляются ВСЕ нотификации по заказу

Тестирование на Demo

На Demo-окружении можно протестировать получение нотификаций по сценариям:

POST /api/v1/orders/{orderNr}/status

{
  "scenario": "delivered"
}

Доступные сценарии

Best Practices

Рекомендации

• Отвечайте быстро — вернуть 200 и обработать асинхронно
• Идемпотентность — обрабатывайте дубли корректно (по sequenceNumber)
• Не валидируйте количество полей — новые поля могут добавляться
• Логируйте всё — тело запроса, время, результат обработки
• Мониторинг — отслеживайте количество ошибок

Обратная совместимость

Lamoda гарантирует:

• Существующие поля не удаляются
• Тип существующих полей не изменяется
• Новые поля могут добавляться

См. также

• Статусы заказов
• Типы нотификаций (подробно)
• Коды ошибок