Типовые проблемы и обходные пути
Симптом → вероятная причина → что сделать. Проверяйте в порядке сверху вниз.
События не приходят вообще
| Симптом | Причина | Решение |
|---|---|---|
| Нет ни webhook, ни handler | Модуль выключен или не operational | Каталог модулей → включить; Лицензирование → проверить ключ; integrations:package:inspect |
| Handler молчит, webhook молчит | Нет подключения на точку заказа | Подключения модулей → инстанс на точку или bulk «все точки», активно |
| Manifest-модуль настроили в Интеграции | Неверный раздел | Для новых модулей используйте Подключения + instance_form (подробнее) |
| Handler молчит | Пустой или неверный hooks.php, класс не в autoload | Исправить FQCN; composer dump-autoload; синхронизировать каталог |
| Webhook молчит | Не настроен URL / неактивен endpoint | Вкладка Исходящие webhooks |
Всё настроено, статус pending | Нет worker на integrations.* | Supervisor на integrations.outbound,integrations.{Code}; queue:restart |
В логе backpressure: skipped | >500 pending у пакета | Разобрать очередь, ускорить handler, временно снизить события |
| Хук не в списке outbound | Фильтр хуков в endpoint | Добавить имя хука или очистить список (= все) |
Только webhook не работает
| Симптом | Причина | Решение |
|---|---|---|
| Handler ok, POST нет | Нет воркера integrations.outbound | Отдельная программа supervisor |
| Job failed в логе | HTTP не 2xx, таймаут | Исправить endpoint; ответ <15 с |
URL rejected | HTTP вместо HTTPS, localhost на prod | HTTPS публичный URL или INTEGRATIONS_DEBUG на dev |
| 401 у вас | Неверная проверка подписи | Canonical JSON всего тела {hook,payload,sent_at} — см. outbound |
Только handler не вызывается
| Симптом | Причина | Решение |
|---|---|---|
| Webhook ok, handler нет | Нет воркера integrations.{Code} | Добавить код модуля в --queue= |
Handler not found | Опечатка в hooks.php | Исправить namespace/class |
completed сразу без эффекта | Идемпотентность — тот же ключ уже был | Норма при повторе; для теста — другой id в simulate |
| Circuit breaker | Серия ошибок в handler | Исправить exception в handler; подождать cooldown |
Inbound
| Симптом | Причина | Решение |
|---|---|---|
503 | Нет inbound_webhook_secret | Задать в credentials инстанса |
401 | Подпись от canonical вместо raw body | HMAC от сырых байт тела |
202, но ничего не происходит | Нет воркера на integrations.{package} | queue:work |
| Handler не вызывается | Нет класса в manifest capabilities | FQCN + IntegrationInboundWebhookHandlerInterface |
403 | Модуль не operational | Лицензия / включение |
REST API
| Симптом | Причина | Решение |
|---|---|---|
401 | Bearer не identifier:secret | Формат из авторизации |
403 scope | Роль без права | Настройка API → роль с нужным scope |
403 на заказ | Ключ привязан к другой точке | Другой ключ или заказ этой точки |
422 статус | Нет status_code/status_id или код не существует | Настройки → Статусы — задать code |
| Сменили статус, CRM не видит | Ждёте только REST | После API уходят хуки — подпишите CRM на order.status_changed |
Статусы и «лишние» хуки
| Симптом | Причина | Решение |
|---|---|---|
Десятки order.item_status_changed | Отмена заказа обновляет все позиции | Слушать только order.status_changed или фильтр по status_semantic |
status_code null в payload | Статус без кода в админке | Заполнить код статуса |
| Робот не меняет позицию, API может | status_locked | Ожидаемо для robot/system; интеграция — отдельное правило |
Лицензия
| Симптом | Причина | Решение |
|---|---|---|
| После деплоя «отвалилось» | Ключ не сбрасывается — модуль выключили / invalid | licenses:verify --force; логи валидатора |
| Cron не проверяет | Нет schedule:run | Crontab |
Legacy (МойСклад и др.)
| Симптом | Причина | Решение |
|---|---|---|
Нет hooks.php событий | Legacy‑модуль без Integration Platform v1 | Старый синк; для событий — новый manifest‑модуль или outbound в обёртке |
| Заказ не в MS | Нет link на товар / org ID / контакт | Синк каталога; организация; телефон/email — см. МойСклад: если не работает |
| Отмена на сайте, в MS без изменений | Статус позиции не cancelled / CANCELLED_ITEM | Настройки → Статусы; не путать с «Выдано» (finished) |
| При выдаче позиция пропала в MS | Старая версия: проверялся finished вместо отказа | Обновить платформу |
| Синк не идёт | Нет worker на default | queue:work --queue=default (не integrations.*) |
| Настроили в Подключениях | МойСkлад — legacy | Только Система → Интеграции |
Чеклист за 5 минут
php artisan integrations:package:inspect {Code}- Operational = да, есть активное подключение
php artisan integrations:hooks:simulate order.created --package={Code}- Очередь хуков → не зависло в
pending tail storage/logs/integrations.log