Вебхуки МойСклад: приём изменений из МойСклад в Битрикс24
Вебхук — это способ МойСклад сразу сообщить модулю: «заказ изменился», «появился новый контрагент». Кладовщик меняет статус заказа на «Отгружен» — МойСклад отправляет уведомление на ваш сайт, модуль ставит задачу в очередь, и сделка в CRM переезжает на нужную стадию.
Без вебхуков обмен работает только в одну сторону — из Битрикс24 в МойСклад.
Страница находится в меню Общие параметры → Вебхуки МойСклад.
Работа с вебхуками состоит из трёх частей, они идут на странице сверху вниз:
- Обработчик на вашем сайте — файл, по адресу которого МойСклад будет присылать уведомления.
- Секретный ключ — пароль, по которому модуль отличает настоящие уведомления от посторонних запросов.
- Вебхуки в аккаунте МойСклад — записи, которые говорят МойСклад, о чём и куда сообщать.
Кнопка Как настроить вебхуки? в верхней части страницы открывает короткую пошаговую инструкцию с картинками.
Настройки страницы
| Настройка | Что делает | По умолчанию |
|---|---|---|
| URL для вебхуков | Адрес обработчика на вашем сайте, куда МойСклад присылает уведомления. Должен начинаться с http:// или https:// и отвечать кодом 200 | Заполняется сам при первом открытии страницы: протокол://адрес-вашего-портала/webhooks/handler.php |
| Секретный ключ | Уникальный ключ, по которому модуль узнаёт свои вебхуки. Запрос без верного ключа обработчик отклоняет | Генерируется сам при первом открытии страницы: случайная строка из 32 латинских букв и цифр |
Адрес и ключ, заполненные автоматически, сразу сохраняются. Протокол и адрес портала берутся из того, как вы сейчас открыли Битрикс24 в браузере.
Адрес обработчика
Слева — поле URL для вебхуков, справа — панель Обработчик со статусом файла и кнопками.
Кнопки у адреса
| Кнопка | Что делает |
|---|---|
| Изменить | Разблокирует поле адреса для правки. Если файл обработчика уже установлен, правка недоступна — появится окно Изменение URL недоступно: сначала удалите файл кнопкой Удалить файл |
| Готово | Появляется в режиме правки. Завершает правку и сразу сохраняет адрес |
| По умолчанию | Появляется в режиме правки. После подтверждения в окне Сброс URL (кнопка Сбросить) возвращает стандартный адрес …/webhooks/handler.php и сохраняет его |
Пока файл установлен, под полем написано «Пока файл установлен, адрес заблокирован от изменений». Ниже показан Путь к файлу обработчика на сервере.
Когда менять адрес. Обычно — никогда: стандартный адрес подходит. Менять стоит, если:
- портал открывается из интернета по другому адресу или протоколу, чем вы зашли сейчас (например, вы работаете по внутреннему адресу, а снаружи сайт доступен по
https://crm.example.ru); - на сайте уже есть что-то по пути
/webhooks/и нужно другое имя папки или файла.
Пример. Сайт доступен снаружи по https://crm.example.ru. Адрес обработчика: https://crm.example.ru/webhooks/handler.php. Своё имя: https://crm.example.ru/ms_hooks/moysklad.php.
В именах папок и файла допустимы только латинские буквы, цифры и знак подчёркивания _, у файла может быть окончание .php. При другом символе под полем появится ошибка вида «Недопустимые символы в имени директории» — кнопка Установить файл станет неактивной.
Панель «Обработчик»: статусы
| Статус | Значит | Что делать |
|---|---|---|
| Файл установлен / Файл не найден | Есть ли файл обработчика на сервере по указанному адресу | Нет файла — нажмите Установить файл |
| Доступ разрешён / Доступ не настроен | Разрешено ли МойСклад обращаться к файлу без входа в Битрикс24 | Не настроен — нажмите Обновить доступ |
| Доступность не проверена | Внешняя проверка ещё не запускалась | Нажмите Проверить доступность |
| Проверяем доступность… | Проверка идёт прямо сейчас | Подождите |
| Доступен извне | Модуль обратился к своему адресу и получил ответ 200 — МойСклад сможет доставлять уведомления | Ничего, всё в порядке |
| Недоступен извне (HTTP …) | Ответ пришёл, но с другим кодом | См. ниже |
| Проверка не удалась | Запрос не состоялся вовсе (адрес не задан, файл не установлен, сетевая ошибка). Текст причины — под кнопками | Исправьте причину и проверьте снова |
Целевое состояние — все три статуса зелёные.
Если у файла нет доступа, Битрикс24 отвечает МойСклад страницей входа вместо обработки уведомления, и уведомления пропадают. При этом в МойСклад вебхуки выглядят созданными. Модуль прописывает разрешение сам — кнопками Установить файл или Обновить доступ.
Панель «Обработчик»: кнопки
| Кнопка | Когда видна | Что делает |
|---|---|---|
| Обновить | Всегда, в заголовке панели | Заново читает статус файла и доступа |
| Установить файл | Файла ещё нет | Копирует файл обработчика на сервер по указанному адресу и сразу открывает к нему доступ |
| Обновить доступ | Файл есть, а доступа нет | Прописывает разрешение на обращение к файлу без входа в Битрикс24 |
| Проверить доступность | Всегда | Модуль сам отправляет запрос на свой адрес и показывает код ответа. Под кнопкой появляется код и адрес, по которому шла проверка |
| Удалить файл | Файл установлен | После подтверждения в окне Удаление файла обработчика (кнопка Удалить) удаляет файл. Все входящие вебхуки перестанут обрабатываться до повторной установки |
Если статус файла загрузить не удалось, в панели будет надпись «Не удалось загрузить статус файла» и ссылка Повторить.
Проверить доступность неактивна, пока на странице есть несохранённые изменения, — под кнопкой появится подсказка «сначала сохраните изменения». Проверять можно только адрес на домене вашего портала.
Если сайт «недоступен извне». Любой код, кроме 200, значит, что обработчик закрыт. Проверьте по порядку: зелёные ли статусы Файл установлен и Доступ разрешён (если нет — Установить файл или Обновить доступ), совпадает ли адрес с тем, по которому сайт открывается из интернета. Если и это в порядке — мешают права на сервере или настройки веб-сервера, тут нужен администратор сервера.
Секретный ключ
Ключ вписывается в адрес каждого вебхука. Когда приходит уведомление, модуль сверяет ключ: без него или с неверным ключом запрос отклоняется и ничего не обрабатывается.
| Элемент | Что делает |
|---|---|
| Поле ключа | Ключ скрыт точками. Значок глаза справа показывает его |
| Сгенерировать | После подтверждения в окне Новый секретный ключ (кнопка Сгенерировать) создаёт новый случайный ключ и сразу сохраняет его |
Ключ можно вписать и вручную — тогда сохраните его кнопкой Сохранить на плавающей панели внизу страницы.
Когда менять. Только если есть подозрение, что ключ попал к посторонним (например, адрес вебхука с ключом переслали в открытый чат).
Ключ входит в адрес вебхука. Старые вебхуки в МойСклад продолжают присылать уведомления со старым ключом, и модуль их отклоняет — импорт молча останавливается. В таблице ниже такие вебхуки помечаются как Ошибка URL. Лечится одной кнопкой Обновить хуки.
Вебхуки в аккаунте МойСклад
Нижний блок показывает, какие вебхуки модуля уже созданы в вашем аккаунте МойСклад, и управляет ими.
Итоговый URL для вебхуков — адрес, который модуль прописывает в каждый вебхук: адрес обработчика, секретный ключ (на странице скрыт точками) и метка модуля. По этой метке модуль отличает свои вебхуки от чужих — вебхуки других интеграций в вашем аккаунте он не трогает.
Таблица вебхуков
Всего модулю нужно 8 вебхуков — по два на каждую сущность:
| Сущность МойСклад | Создание | Обновление |
|---|---|---|
| Заказы покупателей | да | да |
| Заказы поставщикам | да | да |
| Контрагенты | да | да |
| Входящие платежи | да | да |
Вебхуки на удаление модуль не создаёт: удаления из МойСклад он не переносит.
Значки в ячейках (расшифровка — под таблицей и во всплывающей подсказке при наведении):
| Значок | Название | Что значит |
|---|---|---|
| Зелёная галочка | Установлен | Вебхук создан и работает |
| Серый кружок | Не установлен | Вебхука модуля нет |
| Красный восклицательный знак | Ошибка URL | Вебхук есть, но ведёт на старый адрес или со старым ключом — нужно обновить |
| Жёлтый треугольник | Не активен | Вебхук есть, но выключен в МойСклад |
Над таблицей — счётчик Установлено: X / 8. В нём учитываются только рабочие вебхуки — те, что есть в МойСклад, включены и ведут на актуальный адрес с актуальным ключом. Вебхуки с ошибкой адреса и выключенные в счётчик не входят и показываются рядом отдельной цифрой С ошибкой: K. Цель — 8 из 8 и 8 зелёных галочек. Карточка Вебхуки МС на Дашборде считает тот же набор, поэтому цифры там и здесь совпадают.
Кнопки
| Кнопка | Что делает |
|---|---|
| Обновить список | Заново читает вебхуки из МойСклад и перерисовывает таблицу. Ничего не меняет |
| Обновить хуки | Создаёт недостающие вебхуки, а у вебхуков с ошибкой адреса или выключенных исправляет адрес и включает их. Вебхуки модуля на удаление, оставшиеся от прежних версий, снимает. По итогам — сообщение «Вебхуки обновлены: N создано, M обновлено» (если снимались старые хуки — ещё «K лишних удалено») или «Все вебхуки уже актуальны» |
| Удалить все | После подтверждения в окне приложения удаляет из МойСклад все вебхуки модуля, включая старые вебхуки на удаление (чужие не трогает). Сообщение «Удалено N вебхуков модуля» |
Когда нажимать «Обновить хуки»:
- при первой настройке — после того как обработчик стал зелёным;
- после смены адреса обработчика или секретного ключа;
- если в таблице есть красные или жёлтые значки;
- после обновления модуля, если в таблице появились серые кружки (новые сущности для обмена).
Когда нажимать «Удалить все»: при отключении интеграции или переносе портала на другой адрес, чтобы МойСклад не слал уведомления в никуда. После удаления изменения из МойСклад перестанут доходить до Битрикс24.
Вебхуки на удаление модуль не регистрирует: удалённый в МойСклад заказ или контрагент не удаляет сделку, контакт или компанию в CRM. Это защита данных, а не сбой.
Порядок первой настройки
- Проверьте URL для вебхуков: адрес и протокол должны совпадать с тем, как сайт открывается из интернета. При необходимости — Изменить, поправить, Готово.
- Нажмите Установить файл. Статусы Файл установлен и Доступ разрешён должны стать зелёными.
- Нажмите Проверить доступность — нужен статус Доступен извне.
- Секретный ключ уже сгенерирован — ничего делать не нужно.
- Нажмите Обновить хуки и убедитесь, что счётчик показывает Установлено: 8 / 8, а в таблице 8 зелёных галочек.
Проверка в деле: поменяйте комментарий у заказа покупателя в МойСклад, уже связанного со сделкой, — через несколько секунд в очереди обмена появится задача на загрузку.
Не забудьте, что сам обмен документом и контрагентами включается на их страницах: Заказ покупателя, Заказ поставщику, Оплаты, Контрагенты. Вебхуки лишь доставляют уведомления.