SelSup Developers

Сквозной сценарий · Руководства

Вебхуки и событийная интеграция

Настройка исходящих вебхуков, безопасный обработчик, защита от повторов и восстановление пропущенных событий через API.

5 разделовПрактическое руководство
→

Вебхук ускоряет доставку изменений, но не заменяет источник истины. Обработчик должен быть идемпотентным, а периодическая сверка — обязательной.

Событийные интеграции и backend-сервисы

01

Определить события и контракт

Начните с одного бизнес-события: новый или изменённый заказ, изменение остатка либо цены. Для каждого события зафиксируйте владельца данных и действие получателя.

Сохраняйте исходный payload вебхука отдельно от нормализованной модели хотя бы на ограниченный срок. Это помогает повторно обработать событие после исправления интеграции.

Версионируйте свой внутренний обработчик. Новое необязательное поле не должно ломать разбор уже известной структуры.

Связанные методы API

POST/api/webhook/Создать вебхукGET/api/webhook/Получить настройки вебхуков

02

Построить безопасный HTTP-обработчик

  1. 1

    Примите и ограничьте тело

    Разрешите только нужные методы и Content-Type, задайте максимальный размер запроса и короткий таймаут чтения.

  2. 2

    Проверьте источник

    Используйте секрет в непубличном URL или собственном заголовке, если он настраивается, и фильтрацию на API gateway. Не полагайтесь только на User-Agent.

  3. 3

    Сохраните событие

    Запишите payload и ключ дедупликации в одной транзакции, затем быстро верните успешный ответ.

  4. 4

    Обработайте асинхронно

    Выполняйте обращения к ERP, WMS и другим системам из очереди, а не внутри входящего HTTP-запроса.

!
Не выполняйте тяжёлую работу до ответа

Медленный ответ увеличивает риск таймаута и повторной доставки. Сначала надёжно сохраните событие, затем обрабатывайте его из очереди.

Минимальная схема обработчика · JavaScript
app.post('/selsup/events/secret-path', async (request, response) => {
  const eventKey = createStableEventKey(request.body);
  const inserted = await inbox.insertOnce(eventKey, request.body);
  response.sendStatus(inserted ? 202 : 200);
});

03

Повторы, порядок и дедупликация

Обработчик должен считать повтор нормальной ситуацией. Если payload содержит стабильный идентификатор события, используйте его; иначе сформируйте ключ из типа сущности, её id, времени изменения и хеша значимых данных.

События могут прийти не по порядку. Перед записью сравнивайте modifiedDate или повторно получайте актуальную сущность по API.

Возвращайте успешный статус для уже обработанного события. Иначе отправитель может продолжать повторять заведомо завершённую операцию.

i
Inbox-паттерн

Таблица входящих событий с уникальным eventKey, статусом и числом попыток упрощает дедупликацию, повторную обработку и аудит.

04

Восстановить пропущенные события

Даже при стабильных вебхуках запускайте периодическую сверку через API. Для заказов используйте modifiedDate с перекрытием; для остатков — контрольную выборку склада или изменённых SKU.

После простоя обработчика сначала восстановите очередь, затем запросите изменения за весь период простоя. Дедупликация должна объединить вебхуки и результаты API.

Связанные методы API

GET/api/order/findВосстановить изменения заказовGET/api/wms/stock/findСверить изменения остатков

05

Управлять жизненным циклом настройки

Показывайте в своей интеграции активный URL, тип события, дату последнего успешного получения и последнюю ошибку. Так проблему можно диагностировать без доступа к серверным логам.

Перед удалением или заменой URL убедитесь, что новый обработчик принимает события. Старый секрет после миграции следует отозвать.

Связанные методы API

GET/api/webhook/Проверить текущие вебхукиDELETE/api/webhook/{webhookId}Удалить вебхук