Вебхуки Битрикс24: как передавать события и не терять заявки

Входящий вебхук нужен, когда внешняя система вызывает метод REST API Битрикс24, например создаёт запись по заявке сайта. Исходящий вебхук делает обратное: Битрикс24 отправляет событие на ваш обработчик после изменения объекта. Одинаковое слово скрывает разные потоки, права и способы диагностики. Сначала нарисуйте, где возникает событие и какая система должна получить результат.

Документация Битрикс24 указывает, что входящий вебхук работает в рамках выбранных областей доступа и прав сотрудника. Исходящее событие может содержать идентификатор объекта, а подробности обработчик запрашивает отдельно. Не предполагайте, что любой вебхук получает все поля без дополнительного запроса.

Секретный URL входящего вебхука даёт доступ к разрешённым методам от имени создавшего его сотрудника. Храните его как секрет, не добавляйте в публичный JavaScript, скриншоты и журналы ошибок. Выдавайте только нужные области и права; при утечке меняйте ключ по процедуре и проверяйте связанные интеграции.

У внешнего обработчика исходящих событий должна быть проверка источника согласно выбранной схеме Битрикс24 и свой контроль доступа. Не опирайтесь только на то, что адрес сложный. Прежде чем включать обмен на рабочем портале, проверьте действующие требования к подписке и возможность создания вебхуков в конкретной конфигурации.

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

Записывайте идентификатор события, время, тип объекта и итог обработки без секретов и лишних персональных данных. Неуспешную операцию помещайте в видимую очередь на повтор или ручной разбор. Положительный HTTP-ответ обработчика не доказывает, что запись появилась в целевой системе, если работа выполняется позже.

Отправьте обращение с сайта, найдите его в Битрикс24, измените нужное поле и убедитесь, что второе направление обмена выполнилось. Повторите событие и проверьте отсутствие дубля. Затем смоделируйте недоступность целевой системы: ошибка должна быть видна ответственному, а потерянную операцию можно восстановить по журналу.

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