Вебхуки и события RetailCRM

События RetailCRM отслеживают иначе, чем в системах с классическими push-вебхуками. Основной механизм — History API: внешний сервис опрашивает историю изменений заказов и клиентов и синхронизирует только новое. Дополняют его HTTP-действия триггеров и уведомления интеграционных модулей.

Модель событий: pull вместо push

Во многих CRM изменения рассылаются подписчикам push-вебхуками. RetailCRM для основных сущностей использует иную, pull-модель: платформа накапливает историю изменений, а внешний сервис периодически её опрашивает. Это делает обмен предсказуемым и устойчивым к недоступности потребителя.

• Надёжность — пропущенное из-за сбоя изменение не теряется, оно останется в истории;
• Контроль темпа — потребитель сам выбирает частоту опроса;
• Простое восстановление — после простоя достаточно продолжить опрос с последней позиции.

History API

Историю изменений отдают методы GET /api/v5/orders/history и GET /api/v5/customers/history. Каждая запись истории описывает конкретное изменение: какое поле, какой сущности и когда поменялось.

GET /api/v5/orders/history?filter[sinceId]=123456&limit=100

• Запись указывает изменённое поле и его новое значение;
• У каждой записи есть возрастающий идентификатор;
• Ответ поддерживает постраничную выборку.

Помимо заказов и клиентов историю ведут и другие сущности — например, изменения по товарам. Механика везде одна: возрастающие записи, которые потребитель вычитывает по порядку.

Инкрементальная синхронизация по sinceId

Чтобы не перечитывать всю историю, потребитель хранит идентификатор последней обработанной записи и передаёт его в фильтре sinceId. RetailCRM возвращает только записи новее указанной.

1. Сохраните id последней обработанной записи истории;
2. При следующем опросе передайте его в filter[sinceId];
3. Обработайте полученные изменения по порядку;
4. Обновите сохранённый sinceId максимальным id из пачки.

Обработка изменений

История возвращает атомарные изменения полей, а не готовое "событие бизнес-уровня". Задача потребителя — превратить поток изменений в осмысленные действия.

• Смена статуса — изменение поля статуса заказа запускает вашу логику;
• Новая сущность — первое появление заказа или клиента в истории;
• Идемпотентность — повторная обработка одной записи не должна дублировать эффект;
• Группировка — несколько изменений одного заказа полезно свести к одному обновлению.

Обработку строят устойчивой к повторам: при сбое пачку перечитывают с сохранённого sinceId, поэтому одна и та же запись может прийти дважды.

HTTP-действия триггеров

Когда нужно именно уведомление в момент события, применяют триггеры с HTTP-действием. Триггер срабатывает на событие внутри RetailCRM и отправляет запрос на ваш эндпоинт — это ближе к классическому вебхуку, но настраивается через автоматизацию.

• Точечность — реагирует на конкретное условие, а не на весь поток;
• Мгновенность — запрос уходит в момент события;
• Полезная нагрузка — тело формируется средствами автоматизации.

Уведомления интеграционных модулей

Отдельные каналы событий существуют для специализированных интеграций. Message Gateway доставляет события сообщений своим механизмом, а интеграционные модули доставки и оплаты обмениваются статусами по своим сценариям. Это не универсальные вебхуки, а событийные каналы конкретных подсистем.

На практике надёжная интеграция комбинирует эти механизмы: History API как фундамент, триггеры и каналы модулей — как быстрые сигналы поверх него.

Итог

События в RetailCRM — это прежде всего History API с инкрементальной выборкой по sinceId, дополненный HTTP-действиями триггеров и каналами интеграционных модулей. Надёжная синхронизация опирается на курсор, идемпотентную обработку и устойчивость к повторам, а не на предположение о гарантированной доставке push-уведомлений.

Мы проектируем и разрабатываем такие интеграции: инкрементальную синхронизацию с очередями и повторами, обмен с 1С и внешними системами, устойчивый к нагрузке и сбоям. Строим обмен так, чтобы ни одно изменение не потерялось, а данные оставались согласованными.