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

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

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

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

URL

Ваш endpoint должен:

• Принимать POST-запросы
• Быть доступен 24/7
• Работать по HTTPS (URL проходит валидацию @Assert\Url)
• Отвечать быстро (рекомендуется < 5 сек)

Аутентификация

Lamoda поддерживает два режима аутентификации при отправке вебхуков:

Если при создании или редактировании подписки указаны username и password — аутентификация автоматически переключается на basic. Иначе используется none.

Коды ответа

Повторная отправка (retry)

При ошибке доставки (5xx, timeout, connection refused) Lamoda повторяет отправку с увеличивающимся интервалом. Retry-логика управляется инфраструктурой очередей сообщений.

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

Основные типы webhook-нотификаций, доступных для подписки:

Подробнее о каждом типе и структуре данных — см. Типы нотификаций.

Дополнительные REST-события, доступные для подписки:

Не все события доступны для самостоятельной подписки — только те, у которых флаг configurable = true. Уточните у KAM список доступных событий для вашего аккаунта.

Управление подписками через API

Подписками на нотификации можно управлять через Lamoda B2B Platform Partner API:

Создание подписки

POST /notification/subscriptions/
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "partner": 12345,
  "event": "orderStatusChanged",
  "address": "https://your-domain.com/lamoda/webhook",
  "username": "lamoda_webhook",
  "password": "your_secret"
}

Если username и password не указаны — подписка создаётся без аутентификации.

Ограничение: нельзя создать две подписки с одинаковым event + address для одного партнёра (уникальный constraint).

Редактирование подписки

PUT /notification/subscriptions/{id}
Authorization: Bearer YOUR_TOKEN
Content-Type: application/json

{
  "address": "https://new-domain.com/lamoda/webhook",
  "enabled": true,
  "username": "new_user",
  "password": "new_password"
}

Важно: при включении ранее отключённой подписки (enabled: false → true) все накопленные deferred-сообщения автоматически отправляются на ваш endpoint.

Статусы подписки

Каждая подписка имеет один из следующих статусов:

Статусы доставки сообщений

Каждое отдельное сообщение (нотификация) проходит через следующие статусы:

Типы ошибок доставки

При неудачной доставке сообщение содержит одну из следующих ошибок:

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

{
  "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')
    tracking_id = data.get('trackingId')
    sequence = data.get('sequenceNumber')
    
    print(f"Received: {notification_type}, "
          f"TrackingId: {tracking_id}, "
          f"Seq: {sequence}")
    
    # Дедупликация по sequenceNumber
    if is_already_processed(tracking_id, sequence):
        return jsonify({"status": "ok"}), 200
    
    # Обработка по типу нотификации
    if notification_type == 'statusChanged':
        process_order_status(data['data'])
    elif notification_type == 'itemStatusChanged':
        process_item_status(data['data'])
    elif notification_type == 'fulfilmentShipmentStatusChanged':
        process_shipment_status(data['data'])
    
    # Важно: вернуть 200 быстро!
    # Тяжёлую обработку выполняйте асинхронно.
    return jsonify({"status": "ok"}), 200

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

• Отвечайте 200 как можно быстрее. Принимайте нотификацию, ставьте в свою очередь, обрабатывайте асинхронно.
• Используйте sequenceNumber для дедупликации. При переотправке или retry одна и та же нотификация может прийти повторно.
• Игнорируйте неизвестные поля. Lamoda может добавлять новые поля в payload — это обратносовместимая операция.
• Игнорируйте неизвестные типы. Если получили type, который не обрабатываете — просто верните 200.
• Мониторьте статус подписки. Периодически проверяйте GET /notification/subscriptions — статус failing указывает на проблемы с доставкой.
• Настройте fallback через polling. Даже с вебхуками рекомендуется периодически опрашивать GET /orders по updatedAt, чтобы не пропустить обновления.

См. также

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