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

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

Как выбрать API, вебхук или гибридную схему

API — это интерфейс, к которому интегратор обращается с запросом и получает ответ. Через API сайт, CRM, платформа клиентских данных (CDP), сервис рассылок или промежуточный слой могут запросить карточку сделки, создать лид или изменить статус контакта. REST API обычно работает поверх HTTP или HTTPS и предоставляет операции над заданными ресурсами.

Вебхук — это HTTP-запрос, который платформа отправляет на заранее заданный endpoint при наступлении события. Получатель ждет входящее уведомление и не опрашивает источник по расписанию. Такой принцип подписки на события описан в документации Microsoft.

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

API подходит для управляемой работы с состоянием: чтения сущностей, создания записей, обновления полей, получения истории и загрузки набора объектов. Например, API amoCRM поддерживает получение, создание и изменение сделок, включая пакетное добавление и связывание с контактами.

Вебхук запускает реакцию на новую заявку, звонок, смену этапа сделки, отписку от рассылки или зарегистрированную конверсию. Источнику не нужно ждать, пока интегратор отправит следующий запрос.

Гибридная схема соединяет оба механизма. Например, CRM отправляет вебхук после изменения статуса сделки. Интеграция принимает уведомление, запрашивает через API актуальные поля, обновляет целевую систему и позднее сверяет данные. В схеме Calltouch обращения передаются в CRM, а сведения о сделках возвращаются в систему аналитики — такой сценарий описан в документации об интеграции через API и вебхуки. В телефонии Zadarma описывает событийные POST-уведомления о звонках и запросы CRM к API за данными, статистикой и записями.

Polling, то есть периодический опрос API, подходит, когда источник не поддерживает вебхуки, процесс допускает задержку или API позволяет фильтровать записи по времени обновления. Интервал опроса выбирают с учетом квоты запросов и требуемой оперативности.

Матрица выбора API, вебхука и гибридной схемы

Если процесс запускает ваша система, обычно подходит API. Когда поводом служит изменение у поставщика, используют вебхук. Уведомление с сокращенным набором данных дополняют запросом через API.

Какой способ подходит для лидов, звонков, сделок и аудиторий

Для лида с сайта точкой истины часто становится CRM. Форма создает запись через API. Если API возвращает стабильный идентификатор созданной сущности, интеграция сохраняет его и соответствие между лидом, контактом, сделкой и конверсией. Это позволяет связать последующие статусы с рекламным источником и исходной заявкой.

Событие о звонке обычно приходит из телефонии или коллтрекинга. Вебхук может содержать номер, направление и статус звонка. Запись разговора, расширенную атрибуцию или итоговую длительность обработчик запрашивает через API после завершения звонка, если эти данные нужны целевому процессу.

Когда одного payload вебхука недостаточно

Payload — это тело уведомления с данными события. Достаточный состав зависит от целевого действия. Для уведомления менеджера может хватить номера звонящего. Для создания сделки и передачи конверсии нужны дополнительные поля и устойчивые связи между сущностями.

Чек-лист достаточности payload

• Есть стабильный идентификатор лида, контакта, сделки, звонка или конверсии;

• Есть идентификатор события и идентификатор доставки, если платформа их предоставляет;

• Указаны тип события и действие: создание, обновление, удаление, подписка или отписка;

• Есть время изменения, версия или другой признак для сравнения двух событий;

• Переданных полей хватает для операции в целевой системе;

• Понятно, какие значения отсутствуют, скрыты или могут появиться позднее.

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

Пока событие ждет обработки, состояние сущности может измениться. Поэтому команда заранее решает, какие данные использовать: снимок из payload или актуальное состояние из API. Для финансово и операционно значимых действий команда сохраняет исходное событие и отдельно фиксирует данные, прочитанные через API.

Как построить гибридную интеграцию без дублей

Последовательность обработки вебхука

1. Принять запрос по HTTPS и проверить его подлинность способом, который поддерживает поставщик;

2. Проверить тип события и обязательные поля;

3. Сохранить исходный payload, идентификатор доставки и время приема;

4. Вернуть ответ по правилам платформы;

5. Передать событие в очередь или внутреннее хранилище заданий;

6. Проверить, обрабатывалось ли событие раньше;

7. При необходимости запросить актуальную сущность через API;

8. Выполнить целевое действие и записать результат, включая идентификатор созданного объекта.

Короткий ответ обработчика отделяет прием вебхука от операций, которые могут занять больше времени. Тайм-аут устанавливает поставщик. Например, GitHub требует вернуть 2XX в течение 10 секунд и рекомендует вынести дальнейшую обработку в очередь. Это правило GitHub, которое нельзя переносить на CRM и маркетинговые платформы.

Идемпотентность при создании лида

Идемпотентная обработка дает один бизнес-результат при повторном выполнении операции. Для создания лида нужен ключ дедупликации. Лучше использовать стабильный идентификатор события или исходной сущности. Телефон и email подходят как дополнительные признаки: они могут совпадать у разных обращений или меняться.

Перед записью обработчик ищет ключ в журнале и не повторяет завершенную операцию. Если предыдущая попытка остановилась посередине, процесс продолжается с известного состояния. Такой порядок защищает систему от повторного создания записей. В руководстве Microsoft среди рекомендаций упомянут паттерн «Идемпотентный потребитель».

Повторные и переставленные события

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

GitHub использует заголовок X-GitHub-Delivery как уникальный идентификатор доставки. При повторной попытке доставки того же события значение заголовка сохраняется — это указано в рекомендациях GitHub по вебхукам. По этому значению обработчик распознает повторную доставку и не запускает бизнес-операцию заново.

Как восстановить данные после простоя или пропущенных событий

1. Определить период сбоя: записать время последнего успешно обработанного события и время, когда endpoint снова заработал;

2. Найти затронутые сущности: проверить журнал входящих запросов, очередь, ответы обработчика и ошибки целевой системы;

3. Использовать доступную повторную отправку: история доставок, ручная повторная попытка и API управления вебхуками зависят от поставщика;

4. Запросить состояние или изменения через API: использовать фильтр по времени, курсор или выгрузку за период, если API предоставляет такую функцию;

5. Сопоставить идентификаторы: сравнить данные источника, журнал событий и записи целевой системы;

6. Устранить расхождения: создать отсутствующие записи, обновить устаревшие и пометить дубли;

7. Провести контрольную сверку: проверить границы интервала, где чаще проявляются ошибки времени и часовых поясов.

Автоматическая повторная попытка доставки не относится к общим свойствам вебхуков. Например, GitHub не повторяет неудачные доставки автоматически: повторную попытку запускают вручную или программно через REST API. Штатная история для повторной доставки охватывает доставки за последние три дня, как указано в документации GitHub. У CRM, телефонии и сервисов рассылок свои правила.

Какие ограничения API учитывать в эксплуатации

Пагинация и инкрементальная синхронизация

Большую выгрузку не стоит запрашивать одним ответом API. Если API поддерживает пагинацию, интеграция сохраняет номер страницы или курсор, проверяет завершение выборки и продолжает процесс после ошибки. Microsoft рекомендует пагинацию для запросов, способных вернуть много объектов, в руководстве по API.

Фильтр по времени изменения или курсор изменений упрощает регулярную синхронизацию. Команда проверяет наличие, формат и поведение такого механизма в документации конкретного API. Если механизма нет, интеграция выбирает данные с перекрывающимся временным окном и устраняет дубли в результатах.

Rate limits и backoff

Rate limit ограничивает частоту или объем обращений к API. При исчерпании квоты интеграция распознает соответствующий ответ, откладывает запрос и повторяет его по правилам поставщика. Backoff — это управляемое увеличение паузы между попытками. Интервалы задают документация сервиса и заголовки ответа.

Квоты зависят от конкретного API и метода. Например, Google Analytics API применяет лимиты и может отвечать кодами 403 или 429 при их превышении, что зафиксировано в официальной документации.

Периодическая сверка выявляет случаи, когда запрос формально завершился успешно, но бизнес-результат остался неполным: запись создалась без части полей, связь с контактом отсутствует или обновление затронуло устаревшую версию.

Как защитить API и обработчик вебхуков

Защита вебхука

• Принимать запросы по HTTPS;

• Проверять секрет, подпись или другой механизм, предусмотренный платформой;

• Вычислять подпись по исходному телу запроса и безопасно сравнивать ее с подписью поставщика;

• Обрабатывать только ожидаемые типы событий;

• Хранить секрет отдельно от кода и журналов;

• Не помещать токены, API-ключи и персональные данные в URL endpoint.

GitHub рекомендует использовать секрет вебхука, HTTPS и проверку SSL-сертификата, а подписку ограничивать нужными событиями. Меры перечислены в официальных рекомендациях. Битрикс24 рассматривает секретный код вебхука как ключ доступа, который требуется защищать; это указано в учебном разделе платформы.

Защита API

API-токены держат в защищенном хранилище секретов, выдают им минимально необходимые права и ротируют по принятому регламенту. Интеграция журналирует запросы на чтение и запись, связывая каждый из них с событием, заданием очереди и результатом в целевой системе. Секреты и полные персональные данные в логах маскируют.

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

Что мониторить после запуска интеграции

Статус 2XX сообщает отправителю, что обработчик успешно ответил на HTTP-запрос, но не гарантирует сохранение события, создание лида или передачу конверсии. Сквозной контроль связывает идентификатор доставки, исходную сущность, задание очереди, API-запрос и итоговую запись.

Частые вопросы

Можно ли начать с вебхука, а API подключить позже?

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

Нужен ли брокер сообщений для небольшой интеграции?

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

Что делать, если у системы есть API, но нет вебхуков?

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

Можно ли передавать персональные данные в payload вебхука?

Состав данных должен соответствовать цели обработки, применимому законодательству и внутренним политикам компании. Команда передает минимально необходимый набор по HTTPS, исключает персональные данные из URL и ограничивает доступ к payload в журналах и очередях.

Как понять, что готовый коннектор подходит вместо собственной интеграции?

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

Заключение

Архитектуру определяют три условия: кто запускает обмен, какие данные нужны целевой системе и как команда восстановит процесс после сбоя. Зафиксированные заранее правила обработки, дедупликации и сверки помогут выбрать подходящую связку API и вебхуков и оценить объем сопровождения.