Веб-хуки RetailCRM: настройка

Веб-хук — это способ узнать об изменении в CRM мгновенно, без постоянного опроса API. RetailCRM сама отправляет POST-запрос на ваш адрес, как только меняется заказ или клиент.

Что такое веб-хуки и когда их применять

Есть два способа узнавать об изменениях в RetailCRM: периодически опрашивать API (pull) или получать уведомления по мере событий (push). Веб-хуки — это push: CRM инициирует запрос сама.

• Оперативность — реакция в секунды, а не по расписанию опроса.
• Экономия лимитов — не нужно раз за разом дёргать API впустую.
• Событийная логика — «отправить в аналитику при оплате», «уведомить при отмене».

Настройка в интерфейсе

Веб-хуки включаются в настройках API-ключа. При создании или редактировании ключа в разделе Настройки → Интеграция → Ключи доступа к API указывается URL приёмника и выбираются типы событий.

1. Создайте ключ и задайте URL веб-хука — публичный HTTPS-адрес вашего обработчика.
2. Отметьте события: изменения заказов, клиентов, справочников.
3. Сохраните и проверьте, что сервер отвечает кодом 200.

Какие события приходят

RetailCRM шлёт уведомления о ключевых изменениях сущностей. Наиболее востребованные:

В теле события приходит информация об изменившейся сущности и, как правило, перечень изменённых полей. По ним обработчик решает, реагировать или пропустить.

Формат запроса и приёмник

Веб-хук приходит как HTTP POST с JSON-телом. Обработчик должен быстро принять запрос, поставить его в очередь и ответить 200 OK — тяжёлую логику выполнять асинхронно.

Упрощённый приёмник на PHP:

$raw = file_get_contents('php://input'); $event = json_decode($raw, true); if ($event['order']['status'] === 'complete') { queue_push($event); } http_response_code(200);

Ключевое правило: не выполняйте в момент приёма долгих операций (отправку в сторонние API, тяжёлые расчёты). Иначе RetailCRM получит таймаут и посчитает доставку неуспешной.

Безопасность приёмника

Публичный URL может получить и посторонний запрос. Защитите обработчик:

• Секрет в URL — добавьте в адрес непредсказуемый токен и проверяйте его.
• HTTPS — только шифрованное соединение, без http.
• Белый список — при возможности ограничьте источник по адресам RetailCRM.
• Валидация тела — проверяйте структуру JSON перед обработкой.

Идемпотентность и повторы

Одно и то же событие может прийти дважды, а часть событий — потеряться при сбое сети. Надёжный обработчик это учитывает.

1. Идемпотентность — храните обработанные идентификаторы события/заказа, чтобы повтор не сработал дважды.
2. Очередь — принятые события кладите в очередь и обрабатывайте отдельным воркером с повторами.
3. Сверка — раз в час опрашивайте API по фильтру даты изменения и добираете пропущенное.

Связка «веб-хуки плюс периодическая сверка» даёт и оперативность, и полноту: мгновенная реакция на события и гарантия, что ничего не потерялось.

Итог

Настройка веб-хуков RetailCRM — это указание HTTPS-приёмника в API-ключе, выбор нужных событий, быстрый ответ 200 с асинхронной обработкой, защита URL секретом и обязательные идемпотентность и сверка. Так вы получаете события в реальном времени без риска дублей и потерь.

Мы разворачиваем устойчивые приёмники веб-хуков, настраиваем очереди и повторы, связываем события CRM с аналитикой, рассылками и товароучётом. Если нужна событийная интеграция, которой можно доверять в бою, поможем спроектировать и поддержать её.