Типовые проблемы и обходные пути
Симптом → вероятная причина → что сделать. Проверяйте в порядке сверху вниз.
События не приходят вообще
| Симптом | Причина | Решение |
|---|---|---|
| Нет ни 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