Интеграция вчера читала сделки, а сегодня получает 403. Самая частая реакция — создать новый вебхук от администратора и вставить его URL в код. Это возвращает доступ, но одновременно расширяет полномочия интеграции и прячет исходную причину. Через месяц проблема повторяется уже с другим владельцем.
Сначала сохраните один неуспешный ответ целиком: HTTP-код, поле error, сообщение, вызываемый метод и request ID вашей системы. Секретную часть URL вебхука замаскируйте. У Битрикс24 доступ складывается минимум из двух слоёв: scope интеграции и права пользователя, от имени которого идёт вызов.
Не путайте авторизацию и доступ к объекту
Неверный или удалённый webhook обычно даёт проблему авторизации. Действующий webhook без нужного scope не может вызвать метод соответствующего модуля. Даже при наличии scope вызов выполняется в рамках прав владельца: если он не видит сделку или потерял роль после кадрового изменения, интеграция тоже её не увидит. Для REST 3.0 официальная документация отдельно описывает 403 при недостаточном scope и 403 при отсутствии доступа к объекту.
| Что проверить | Сигнал | Следующий шаг |
|---|---|---|
| Метод и URL | Опечатка или чужой портал | Сверить домен и имя метода |
| Scope | Нет доступа к модулю CRM | Проверить права интеграции |
| Владелец webhook | Уволен или переведён | Проверить активность и роль |
| Конкретный объект | Другие сделки читаются | Сравнить категорию и владельца |
Проверка 1. Повторите один безопасный read-запрос
Не начинайте с метода изменения. Возьмите чтение заранее известной тестовой сущности и выполните запрос сервером, где хранится интеграция. Не вставляйте webhook URL в тикет, чат или публичный скриншот.
curl -sS -X POST "https://portal.example/rest/USER/SECRET/crm.deal.get.json" -H "Content-Type: application/json" --data '{"id":123}'PASS: ответ содержит result с тестовой сделкой. FAIL: возвращаются 403 и код ошибки. Если метод чтения проходит, а изменение нет, не трогайте transport: проверяйте права на изменение и состояние самой сущности.
Проверка 2. Сверьте scope интеграции
Для входящего вебхука откройте Разработчикам → Готовые сценарии → Другое → Входящий вебхук и найдите используемую интеграцию. Названия пунктов могут отличаться между интерфейсами портала, поэтому ориентируйтесь на раздел локальных интеграций. В карточке нужен scope, указанный в документации вызываемого метода. Для методов CRM это обычно crm; не выдавайте телефонию, задачи и диск «на всякий случай».
PASS: нужный scope включён, метод относится к нему. FAIL: метод требует модуль, которого в карточке нет. После изменения снова выполните тот же read-запрос, не меняя одновременно пользователя и код.
Проверка 3. Проверьте пользователя, а не только webhook
Запрос выполняется с правами сотрудника, создавшего вебхук. Проверьте, активен ли он, в каком отделе находится и какую CRM-роль получил. Затем войдите под тестовой учётной записью с той же ролью и откройте целевой объект через интерфейс. Так вы отделите REST от модели доступа.
PASS: пользователь видит и может выполнить нужное действие в интерфейсе. FAIL: карточка скрыта, доступна только на чтение или относится к другой категории сделок. Исправляйте роль минимально, а не назначайте владельца администратором.
Проверка 4. Сравните доступный и недоступный объект
Если один ID читается, а другой даёт отказ, scope уже менее вероятен. Сравните направление сделки, ответственного, отдел владельца и тип операции. Такой A/B тест полезнее перевыпуска токена: он показывает, какое правило прав срабатывает.
Алгоритм диагностики
- Сохраните код и тело одного ответа 403 без секрета.
- Сверьте домен портала и название метода.
- Повторите безопасный read-запрос к тестовой сущности.
- Проверьте требуемый scope на странице метода.
- Проверьте активность и CRM-роль владельца webhook.
- Сравните доступ к двум объектам разных категорий.
- После одного изменения повторите исходный запрос.
Ошибки, которые усложняют расследование
- Создавать webhook администратора вместо поиска причины.
- Менять scope, роль и код одновременно.
- Проверять доступ методом удаления или изменения production-сделки.
- Публиковать полный URL вебхука в журнале.
- Считать любой 403 сетевой блокировкой.
Чек-лист
- Секрет URL не попал в лог.
- Есть точный код ошибки и метод.
- Scope метода подтверждён документацией.
- Владелец webhook активен.
- Его роль проверена через интерфейс.
- Контрольный read-запрос безопасен.
- После исправления проверены только необходимые права.
Что делать, если не помогло
Соберите обезличенный пакет: время, домен портала, имя метода, HTTP-код, error-код, ID тестового объекта, роль владельца и список scope без секретного URL. Если все объекты дают одинаковый отказ, начинайте со scope и владельца. Если отказ зависит от объекта, разбирайте CRM-роли и категорию. Если интерфейс разрешает действие, а REST запрещает, сверяйте метод, его scope и контекст авторизации.
Отдельно проверьте, не сменился ли владелец интеграции после увольнения, переноса между отделами или восстановления портала из копии. Такой контекст часто объясняет внезапный отказ без изменений в коде. Зафиксируйте состояние пользователя и роли рядом с runbook интеграции, чтобы следующий инцидент начинался со сравнения, а не с выпуска нового секрета.
CTR1 может проверить CRM, роли и интеграции Битрикс24. Дополнительно пригодятся статьи про выбор REST API или webhook, права отдела продаж и ревизию ролей после изменений.
