Отслеживание кликов по ссылкам в HubSpot: запись кликов в таймлайн сделки

Если ваш отдел продаж живёт в HubSpot, а отслеживание кампаний ведётся в инструменте для коротких ссылок, у вас два таймлайна, которые никогда не пересекаются. Маркетолог видит клики; AE видит этапы сделок. Никто не видит связи между ними. Это руководство объясняет, как соединить Elido с HubSpot так, чтобы каждый клик по короткой ссылке отображался в таймлайне контакта, UTM-значения попадали в свойства CRM, а пороги кликов могли двигать этапы сделок вперёд.

Механизм держится на трёх API HubSpot: Timeline Events API для записей о каждом клике, Contacts API для записи свойств и Deals API для продвижения этапов. Аутентификация - OAuth 2.0 с областями доступа из документации HubSpot OAuth scopes. HubSpot работает в Elido с апреля 2026, и коннектор берёт на себя ротацию токенов обновления, повторные попытки и идемпотентные записи в таймлайн. Остальное - настройка.

TL;DR

• Подключение через OAuth с тремя областями: crm.objects.contacts.write, crm.objects.deals.read, timeline. Без всех трёх HubSpot отклонит установку.
• Elido публикует каждый клик как Timeline Event с eventTemplateId, созданным при установке. UTM-параметры попадают в payload события и в три пользовательских свойства контакта (elido_last_utm_source, _campaign, _medium).
• Аналитические свойства HubSpot вроде original_source_drill_down_1 - только для первого касания. Используйте пользовательские свойства для текущей атрибуции, не встроенные.
• Правила порога кликов (например, "50 кликов по ссылке на коммерческое предложение переводит сделку на этап Engaged") выполняются на сервере в api-core. Настраивайте их в параметрах рабочего пространства, а не в рабочих процессах HubSpot.
• Ошибки 401 в интеграции почти всегда означают нарушенную цепочку токенов обновления. Переустановите через плитку маркетплейса - не вставляйте токены вручную.

Как клики попадают в таймлайн контакта HubSpot

Клик по короткой ссылке Elido проходит пять шагов, прежде чем появиться в HubSpot.

1. Обработчик переадресации на edge (services/edge-redirect) читает клик, определяет назначение и записывает событие клика в Redpanda. Это горячий путь, p50 около 5 мс; HubSpot никогда не находится на пути запроса.
2. click-ingester читает топик Redpanda и сохраняет данные в ClickHouse для аналитики.
3. Коннектор HubSpot внутри api-core (до консолидации - services/hubspot-connector) подписывается на fan-out топик. Для каждого клика в рабочем пространстве с подключённым HubSpot он формирует payload Timeline Event.
4. Коннектор определяет контакт: если клик содержит contact_id Elido (заданный через параметр ?eid= или общий доступ к дашборду от авторизованного пользователя), он напрямую маппится на контакт HubSpot. Если есть только fbclid или gclid, Elido пробует сопоставление по email из последней формы в течение 14 дней; иначе событие помещается в очередь ожидания на 72 часа.
5. Коннектор делает POST на /crm/v3/timeline/events с ID шаблона события, созданного при установке. Запись в таймлайн идемпотентна по eventId, поэтому повторные попытки безопасны.

Payload события содержит tokens для структурированных полей, которые отображает HubSpot (слаг ссылки, URL назначения, название кампании, страна, устройство), и extraData для всего остального (полный набор UTM, реферер, фрагменты user-agent, необработанная временная метка). Интерфейс таймлайна HubSpot рендерит токены; extraData доступны через API, но скрыты в стандартном представлении.

Маппинг UTM на свойства

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

Аналитические свойства (только первое касание). original_source_drill_down_1, hs_analytics_first_url, hs_analytics_first_referrer и остальные из семейства hs_analytics_* устанавливаются один раз - при первом создании контакта. Последующие записи через Contacts API молча отбрасываются. HubSpot не возвращает ошибку - значение просто не меняется. Если вам казалось, что значение "последней кампании" застряло в 2024 году, вот почему.

Пользовательские свойства (чтение/запись). Всё, что вы определяете сами, можно свободно перезаписывать. Elido создаёт три свойства при первом подключении: elido_last_utm_source, elido_last_utm_campaign, elido_last_utm_medium. Каждый клик отправляет PATCH с этими свойствами на разрешённый контакт. Свёртка на уровне сделки использует самые актуальные значения через рабочий процесс HubSpot, копирующий из основного контакта.

Рисунок 2 ниже обобщает маппинг, который Elido применяет по умолчанию. Любую строку можно переопределить в параметрах рабочего пространства - Интеграции - HubSpot - Маппинг полей. Для детального разбора UTM-гигиены сквозное руководство по UTM охватывает соглашения об именовании, а руководство по шаблонам UTM объясняет, как применять их при создании ссылок.

Реальный пример

B2B SaaS-аккаунт регистрируется на вебинар. В письме с дополнительными материалами - короткая ссылка Elido на PDF с ценами с UTM utm_source=webinar&utm_campaign=q2-pricing&utm_medium=email. Получатель кликает дважды за два дня. В HubSpot:

• На контакте появляются два новых события таймлайна с заголовком "Клик: PDF с ценами Q2 (s.elido.me/abc123)".
• elido_last_utm_source = webinar, elido_last_utm_campaign = q2-pricing, elido_last_utm_medium = email.
• Существующее original_source_drill_down_1 контакта (установленное в сентябре, когда он скачал электронную книгу) не меняется. Это корректное поведение первого касания, а не ошибка.
• Свойство elido_recent_link_clicks связанной сделки увеличивается на 2 через рабочий процесс HubSpot, отслеживающий свойства контакта.

AE, смотрящий на сделку, видит растущий счётчик кликов до того, как позвонит. Маркетолог, ведущий вебинар, может применить фильтр списка HubSpot по elido_last_utm_campaign = q2-pricing и отправить его в последовательность повторного вовлечения. Одни данные, два угла зрения.

Привязка порогов кликов к этапам сделок

Видимость в таймлайне - это базовый уровень. Правила порогов - это то, где интеграция показывает настоящую ценность: они превращают сигнал кликов в действие CRM без необходимости кому-то следить за дашбордом.

Структура правила:

trigger:
  link_tag: "sales-collateral" # all links tagged this way count
  contact_window: 30d # rolling
  click_threshold: 50
action:
  type: advance_deal_stage
  pipeline: "default"
  from_stage: "appointmentscheduled"
  to_stage: "qualifiedtobuy"
  guard:
    require_associated_contact: true
    deal_amount_min: 5000 # only deals worth advancing

Правила живут в api-core и выполняются на том же fan-out топике, который обеспечивает записи в таймлайн. Каждый клик пересчитывает скользящий счётчик для (contact_id, link_tag). Когда счётчик превышает порог и контакт связан со сделкой в from_stage, коннектор отправляет PATCH на /crm/v3/objects/deals/{dealId} с properties.dealstage = qualifiedtobuy.

Несколько практических замечаний.

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

Блок guard имеет значение. Без require_associated_contact анонимные клики (кто-то переслал ссылку другу) могут активировать правило. Без deal_amount_min вы будете продвигать пробные сделки за 5000 рублей в этапы, предназначенные для корпоративных клиентов.

Обратные правила не симметричны. Elido не понижает этапы автоматически при неактивности, потому что отчёты HubSpot рассматривают откаты этапов как подозрительные. Если нужна обработка застывших сделок, создайте рабочий процесс HubSpot на основе hs_lastmodifieddate, а не правило Elido.

Подробности механизма пересылки конверсий - в руководстве по пересылке конверсий: схема событий, политика повторных попыток и очередь "мёртвых писем". Страница функций отслеживания конверсий показывает тот же поток для Meta CAPI, GA4 и Mixpanel; HubSpot - одно из нескольких направлений.

Выбор между правилами на основе тегов и на основе ссылок

Есть два способа ограничить область действия правила порога. На основе тегов охватывает набор ссылок с одним тегом (например, все 12 ссылок в нурчуринговой последовательности Q2 считаются к одному порогу). На основе ссылки - только одна короткая ссылка.

Используйте на основе тегов, когда путь потенциального клиента охватывает несколько точек касания (в B2B так почти всегда). Используйте на основе ссылки, когда сам актив является сигналом - единственная ссылка на коммерческое предложение, где клик с третьего раза означает, что сделка реальна. Оба типа правил сосуществуют; один account engineer недавно настроил рабочее пространство с 8 правилами на основе тегов и 14 на основе ссылок, работающими параллельно без конфликтов.

Ротация токенов обновления и ошибка 401, которую вы вот-вот увидите

OAuth HubSpot использует ротирующиеся токены обновления. Каждый вызов /oauth/v1/token с grant_type=refresh_token возвращает новый токен обновления и аннулирует предыдущий. Это хорошо для безопасности и отвратительно для тех, кто пытается управлять токенами вручную.

Коннектор Elido правильно обрабатывает ротацию. Поток:

1. Токен доступа истекает каждые 30 минут (настройка HubSpot по умолчанию; значение expires_in в ответе токена это подтверждает).
2. Примерно за 90 секунд до истечения коннектор обращается к эндпоинту обновления с текущим токеном обновления.
3. HubSpot возвращает новый access_token + новый refresh_token + новый expires_in.
4. Elido атомарно сохраняет оба в таблице токенов. Старый токен обновления теперь недействителен.

Ситуации, в которых это ломается:

Восстановление базы данных. Если восстановить резервную копию старше последнего обновления, сохранённый токен уже аннулирован на стороне HubSpot. Первый вызов обновления вернёт 401 с BAD_REFRESH_TOKEN. Симптом: все вызовы API HubSpot из Elido падают до переустановки.

Копирование токенов между окружениями. Разработчик копирует токены HubSpot рабочего пространства из стейджинга на локальную машину. Оба окружения теперь пытаются обновиться по одному токену. Кто успеет первым - побеждает; второй гибнет при следующей попытке.

Ручное редактирование строки токена. Заманчиво при отладке, никогда не является хорошей идеей. Столбец token_version инкрементируется атомарно при обновлении; ручные правки нарушают проверку оптимистичного параллелизма, и следующее обновление провалится.

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

Решение во всех четырёх случаях одинаково: откройте плитку маркетплейса HubSpot в параметрах рабочего пространства, нажмите "Переустановить", примите области доступа. HubSpot выдаст новый код авторизации, Elido обменяет его на новую пару токенов, и интеграция возобновится. Данные не теряются; события таймлайна, стоявшие в очереди во время сбоя, выгружаются за минуту. В документации HubSpot OAuth поток кода авторизации описан подробнее.

А как насчёт интеграций через вставку токенов?

Некоторые поставщики позволяют вставить токен доступа Private App вместо OAuth. HubSpot это поддерживает, и это полностью обходит проблему ротации - токены Private App не истекают и не ротируются. Elido не использует этот путь для HubSpot, потому что Private Apps привязаны к одному аккаунту HubSpot и не могут устанавливаться на несколько порталов из одного рабочего пространства Elido. Если у вас только один портал HubSpot и хочется пропустить установку через маркетплейс, напишите через /contact; коннектор поддерживает оба режима, просто второй не отображается в стандартном интерфейсе.

Мониторинг цепочки обновления

Два сигнала говорят о том, что обновление работает нормально.

Счётчик Prometheus hubspot_refresh_attempts_total{result="ok|error"} находится в api-core. Устойчивый процент ошибок выше 1% по рабочему пространству - это ранний предупредительный сигнал. Большинство рабочих пространств показывают ноль ошибок неделями. Руководство по наблюдаемости объясняет, как подключить это к алертам.

Страница "Интеграции" в параметрах рабочего пространства показывает временную метку последнего успешного обновления по каждой интеграции. Если HubSpot говорит "Последнее обновление: 6 дней назад", а у остальных - минуты, именно это рабочее пространство нужно проверить первым.

Собираем всё вместе

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

1. Установите из /integrations, примите три области доступа. Подождите 60 секунд, чтобы HubSpot успел создать шаблон события таймлайна.
2. Подтвердите первый клик. Отправьте себе короткую ссылку Elido с ?eid=<ваш_hubspot_contact_id>, кликните по ней с другого устройства, обновите страницу контакта в HubSpot. Событие таймлайна должно появиться в течение 30 секунд.
3. Добавьте три пользовательских свойства Elido в представление контакта. Параметры рабочего пространства - Контакты - Настроить боковую панель. Здесь маркетинг и продажи наконец видят одинаковые UTM-значения.
4. Подождите две недели, прежде чем настраивать правила порогов. Нужны реальные данные кликов, чтобы понять, что означает "высокое намерение" для вашего набора активов; произвольные пороги в день установки почти всегда ошибочны. Страница решений для маркетологов и введение в аналитику ссылок помогут определить, что измерять.
5. Настройте первое правило для одного актива с высоким намерением (страница с ценами, ссылка на коммерческое предложение). Наблюдайте неделю. Скорректируйте порог и ограничение по сумме сделки. Повторяйте.

Полный набор функций задокументирован в каталоге интеграций, а исходный код коннектора находится в пакете hubspot в services/api-core. Если вы оцениваете платформу в целом, Elido pricing показывает тариф, в который включена интеграция с HubSpot (Pro и выше), а обзор серверного отслеживания конверсий сравнивает HubSpot с другими CRM и аналитическими направлениями, куда Elido пересылает данные.

Финальное практическое правило: считайте события таймлайна источником истины об активности; пользовательские свойства - источником истины о последней кампании; никогда не доверяйте семейству hs_analytics_* ни для чего, кроме первого касания. Этот триплет закрывает 95% того, о чём спорят маркетинг и продажи, и модель данных HubSpot наконец начинает казаться честной.