API и вебхуки простыми словами: как сервисы обмениваются данными

API — это набор правил, по которым одна программа может запросить данные у другой или попросить её что-то сделать: создать сделку, выставить счёт, вернуть остатки товара. Вебхук — обратный механизм: сервис сам отправляет сообщение по заранее указанному адресу, как только что-то произошло, например пришла оплата. Проще говоря, через API вы спрашиваете «что нового?», а вебхук сам сообщает «произошло вот это». Интеграция по API — это связка, в которой сайт, CRM, платёжный сервис и учётная система обмениваются данными без ручного переноса.

Что такое API простыми словами

Удобная аналогия — окно выдачи в ресторане. Посетитель не заходит на кухню и не берёт продукты сам: он делает заказ по меню, а кухня возвращает готовое блюдо. Меню — это документация API: в ней перечислено, что можно попросить и в каком виде. Заказ — это запрос, блюдо — ответ.

В мире сервисов это выглядит так: сайт отправляет в CRM запрос «создай контакт с таким именем и телефоном», CRM проверяет, есть ли у отправителя право на это, выполняет действие и отвечает «готово, вот номер контакта» или «ошибка, телефон не указан». Человек в этом не участвует, всё занимает доли секунды.

Важно понимать три вещи:

• API есть не у всех сервисов, и возможности у разных систем отличаются. Одна CRM позволяет через API управлять почти всем, другая — только создавать заявки.
• API — это не готовая интеграция. Это «розетка», к которой ещё нужно подключить «вилку»: код, модуль или сервис-посредник.
• Доступ к API выдаёт владелец аккаунта. Без ключа или токена, о которых ниже, ни один запрос не пройдёт.

Что такое вебхук

Если API — это когда вы звоните в службу доставки и спрашиваете, где курьер, то вебхук — это СМС «курьер у двери», которое приходит само. Вы один раз сообщаете сервису адрес, куда присылать уведомления, и выбираете события, о которых хотите знать. Дальше сервис сам отправляет сообщение каждый раз, когда событие происходит.

Технически вебхук — это обычный запрос, который сервис-отправитель делает на ваш адрес (URL) с данными о событии: какой платёж, на какую сумму, с каким статусом. Принимающая сторона должна быстро ответить «получено». Если ответа нет, хорошие сервисы повторяют отправку. Например, ЮKassa ждёт в ответ код 200 и, если не получает его, повторяет уведомление в течение 24 часов с момента события.

Название немного путает: в Битрикс24 есть и «входящие», и «исходящие» вебхуки. Входящий — это, по сути, готовый адрес с ключом для обращения к API Битрикс24 извне. Исходящий — классический вебхук: Битрикс24 сам сообщает внешней системе о событии, например о создании сделки.

API и вебхук: в чём разница

Главное отличие — кто начинает разговор. При работе через API инициатор — ваша система: она запрашивает данные, когда ей нужно. При вебхуке инициатор — внешний сервис: он присылает данные, когда что-то изменилось.

На практике они почти всегда работают в паре. Вебхук сообщает: «платёж такой-то изменился». Интеграция получает уведомление и через API запрашивает у сервиса актуальное состояние платежа — так проверяется, что уведомление настоящее и данные свежие. Именно так рекомендует делать ЮKassa: не верить уведомлению на слово, а сверить статус объекта через API.

Опрашивать сервис через API каждые несколько секунд «вместо вебхука» — плохая идея: это тратит лимиты и всё равно даёт задержку. Если у сервиса есть вебхуки на нужное событие, лучше использовать их.

Примеры из бизнеса

Заявка с сайта в CRM. Самый частый сценарий: форма на сайте отправляет данные через API в amoCRM или Битрикс24, там создаются контакт и сделка, ответственному приходит задача. Подробно о подводных камнях — дублях, UTM-метках, резервной копии — мы писали в отдельной статье о том, как подключить формы сайта к CRM без потери заявок.

Оплата меняет статус сделки. Клиент оплачивает счёт на сайте через ЮKassa. ЮKassa отправляет вебхук о событии payment.succeeded, интеграция находит в CRM сделку по номеру заказа, переводит её на этап «Оплачено», ставит задачу менеджеру и при необходимости отправляет клиенту письмо. Без вебхука менеджер узнавал бы об оплате из выписки — через день.

Обмен с 1С. Сайт или CRM получает из 1С цены, остатки и статусы отгрузок, а в 1С уходят заказы и данные покупателей. Здесь обычно используется расписание (обмен раз в несколько минут или раз в час) и стандартные механизмы обмена 1С, а не вебхуки на каждое событие. Ключевой вопрос такой интеграции — какая система главная для каждого типа данных: цены живут в 1С, контакты — в CRM, и правило не должно нарушаться.

Уведомления и отчёты. Вебхук о новой сделке — сообщение в рабочий чат Telegram. Ежедневный запрос через API к CRM и рекламным кабинетам — сводная таблица для собственника. Всё это та же логика «запрос или уведомление», только с другими участниками.

Ключи, токены и права доступа

Чтобы сервис выполнил запрос, он должен понять, кто спрашивает и что этому отправителю разрешено. Для этого используются ключи и токены — по сути, электронные пропуска.

• API-ключ — длинная секретная строка, которую сервис выдаёт в настройках аккаунта. Кто знает ключ, тот действует от имени аккаунта. Поэтому ключ не пересылают в мессенджерах, не вставляют в код сайта, видимый в браузере, и не хранят в общих таблицах.
• Токен доступа — временный пропуск, который выдаётся после подтверждения владельцем аккаунта. У токена бывает срок жизни: истёк — интеграция перестаёт работать, пока его не обновят. Это одна из самых частых причин «всё работало, а потом перестало».
• Права доступа — что именно разрешено пропуску: только читать сделки или ещё и удалять их. Правило простое: выдавать минимум, необходимый для задачи. Интеграции, которая создаёт заявки, не нужно право выгружать всю базу клиентов.

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

Лимиты, ошибки и журнал

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

Для бизнеса это значит: массовая загрузка тысяч контактов или ежеминутная синхронизация всего каталога требуют продуманного темпа, иначе интеграция упрётся в лимит в самый неудобный момент. Кроме лимитов, бывают и обычные сбои: сервис на обслуживании, пропала связь, поменялось поле в CRM.

Надёжная интеграция отличается от «как-то работающей» тремя вещами:

• Повторные попытки. Если запрос не прошёл, он повторяется через нарастающие интервалы, а не теряется.
• Защита от дублей. Если повтор всё-таки прошёл дважды, второй раз не должен создавать вторую сделку или второй платёж. Для этого каждое событие помечается уникальным номером и проверяется перед обработкой.
• Журнал и оповещения. Каждый обмен записывается: что отправили, что ответил сервис. Если ошибки повторяются, ответственный получает сообщение, а не узнаёт о проблеме от клиента.

Готовые коннекторы или своя интеграция

Сервисы-посредники вроде n8n, Make и Albato позволяют собрать интеграцию из готовых блоков без программирования: «когда пришла заявка — создай сделку — отправь сообщение в Telegram». У них есть журнал запусков, повторы и визуальная схема, которую понимает не только разработчик. Albato ориентирован на российские сервисы, n8n можно развернуть на собственном сервере, что удобно для требований к хранению персональных данных.

Своя интеграция — это код, который напрямую обращается к API нужных систем. Она нужна, когда логика сложная, объёмы большие, у сервиса нет готового блока в коннекторе или каждый вызов посредника стоит заметных денег при высоких объёмах.

Что выбрать: практическое правило

Правило, которым мы пользуемся при проектировании интеграций между сервисами:

• Две-три системы, стандартные события, понятная логика — коннектор. Быстрее запуск, проще поддержка, изменения можно вносить без разработчика.
• Нестандартная логика, большие объёмы, обмен с 1С или собственной базой — своя интеграция через API с очередью, повторами и журналом. Подробнее — на странице разработки интеграций через API и вебхуки.
• Смешанный вариант — частый и разумный выбор: простые сценарии в n8n, сложный обмен — отдельным модулем.

Если сервис умеет присылать вебхук о нужном событии, стройте схему на нём, а API используйте для проверки и записи данных. Опрос по расписанию оставьте для систем, где вебхуков нет.

Как поставить задачу на интеграцию

Хорошее техническое задание экономит недели переписки. Достаточно ответить на вопросы:

• Какие системы участвуют и у кого есть административный доступ к каждой.
• Какое событие запускает обмен: новая заявка, оплата, смена этапа, расписание.
• Какие данные передаются и куда: соответствие полей «здесь — там», включая обязательные.
• Какая система главная для каждого типа данных, если они есть в обеих.
• Что делать при ошибке: кому сообщать, допустима ли задержка, нужен ли ручной разбор.
• Ожидаемые объёмы: десятки событий в день или тысячи в час.
• Как проверить результат: несколько тестовых сценариев, которые должны пройти перед запуском.

Схема на одну страницу со стрелками «откуда — куда — когда» часто полезнее длинного документа. С ней разработчик сразу видит, где нужен вебхук, где запрос по API и где возможны узкие места.