Схема POST
Запрос POST, отправленный на webhook, будет в формате JSON со следующей схемой:
Полезная нагрузка Webhook Proto
// Represent user lead data for single column
message UserLeadColumnData {
  // Human-readable text of the field type (e.g.: Full Name,  What is your
  // preferred dealership?). This field might not always be populated.
  optional string column_name = 1;
  // Column value based on column type
  oneof column_value {
    string string_value = 2;
  }
  // Column ID. Populated for all types of fields. (e.g.: FULL_NAME)
  optional string column_id = 3;
}
// Message to construct webhook JSON payload
message WebhookLead {
  // Unique ID to represent lead
  optional string lead_id = 1;
  // User inputted data per column
  repeated UserLeadColumnData user_column_data = 2;
  // API version
  optional string api_version = 3;
  // Form ID to which lead belonged to.
  optional int64 form_id = 4;
  // Campaign ID that the lead form is associated with
  optional int64 campaign_id = 5;
  // Key to be used by advertiser to verify the request
  // is from Google.
  optional string google_key = 6;
  // Denotes if the lead is a test lead.
  optional bool is_test = 7;
  // Click ID for the lead submission.
  optional string gcl_id = 8;
  // Adgroup ID which generated the lead.
  optional int64 adgroup_id = 9;
  // Creative ID which generated the lead.
  optional int64 creative_id = 10;
  // Asset group ID represents the container for holding assets, associated
  // URLs, hints and criteria that will be used to select assets and for
  // optimization. This field is only populated for Performance Max campaigns.
  int64 asset_group_id = 11;
  // Lead stage at the time of delivery.
  string lead_stage = 12 [(datapol.semantic_type) = ST_NOT_REQUIRED];
  // Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z
  string lead_submit_time = 13 [(datapol.semantic_type) = ST_NOT_REQUIRED];
}
Описание поля
| Поле | Описание | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| lead_id | Уникальная строка, идентифицирующая данный лид. Рекомендация по обработке: используйте это для дедупликации лидов, которые получены. Это будет уникально для всех форм. При сообщении о проблемах, связанных с определенным лидом, этот идентификатор будет необходим. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| api_version | Версия API, к которой относится эта схема лида. Она будет использоваться при переходе на новую схему и может быть проигнорирована на данный момент. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| form_id | Уникальный идентификатор для каждой формы, настроенной в Google Ads. Текущий продукт позволяет прикреплять форму с уровнем кампании (в отличие от присоединения на уровне группы объявлений или объявлений).  Последствия: Лиды можно разделять только на уровне  Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| campaign_id | Идентификатор кампании Google Ads или идентификатор позиции (Display & Video 360) прикрепленной формы лидов. Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adgroup_id | Идентификатор группы объявлений Google Ads используется для различения определенной группы объявлений в кампании. (Доступно только для лидов из видеорекламы и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| creative_id | Идентификатор креатива Google Ads используется для различения конкретного креатива в группе объявлений. (Доступно только для лидов из видеорекламы и объявлений Discovery) Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gcl_id | Идентификатор клика Google — уникальный параметр, используемый для отслеживания каждого клика по объявлению. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| google_key | Ключ, настраиваемый рекламодателем для каждой формы.  Рекомендация по обработке: Перед обработкой лида, полученного через webhook, проверка  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_test | Это поле имеет «необязательную» семантику. Если значение равно true, рассматривать этот лид как тестовый лид. Если значение равно false или поле отсутствует, рассматривать этот лид как допустимый производственный лид. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| user_column_data | Повторяющийся кортеж «ключ-значение», передающий отправленные пользователем данные. 
 
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| asset_group_id | Это поле заполняется только для кампаний Performance-Max. Это обозначает идентификатор контейнера, который содержит лид-форму. Для обработки клиентам необходимо использовать 8-байтовое целое число. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_stage | Это обозначает стадию лида на момент доставки лида. Это поле полезно для отслеживания стадии воронки/статуса конверсии лида. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_submit_time | Это обозначает временную метку, в которую пользователь отправил форму. Она представлена в формате ISO-8601. Например, 2024-09-26T12:30:00Z | 
Нераспознанные поля и прямая совместимость
Чтобы обеспечить надежную интеграцию веб-перехватчика и возможность адаптации к будущим улучшениям, рекомендуется спроектировать анализатор JSON так, чтобы он корректно игнорировал любые поля в полезной нагрузке веб-перехватчика, которые ваша система явно не использует или не распознает.
Основная рекомендация: настройте логику анализа JSON для обработки только тех полей, которые вам требуются для вашего приложения. Не пишите код, который ожидает фиксированный набор полей или который даст сбой, если в полезной нагрузке будут присутствовать новые, неожиданные поля.
Почему это важно:
- Совместимость вперед: Google может добавлять новые, необязательные поля в полезную нагрузку веб-перехватчика в будущих обновлениях, чтобы предоставлять более полные данные или новые функции. Если ваш парсер слишком строг (например, не справляется с неизвестными свойствами), ваша интеграция может сломаться, когда такие неломающие изменения будут развернуты Google.
- Упрощенное обслуживание: сосредоточившись только на тех точках данных, которые вы активно используете, ваш код интеграции становится проще и легче в обслуживании.
Большинство современных библиотек анализа JSON по умолчанию предлагают возможность игнорировать неизвестные свойства или могут быть настроены для этого.
Обработка свинца
Обработчики лидов должны отвечать следующими HTTP-кодами:
| HTTP-ответ | Тело ответа (JSON) | Повторяемая ошибка? | 
|---|---|---|
| 200 | {} | Н/Д | 
| 4XX | {"сообщение: Текст ошибки в свободной форме, описывающий, что было не так с запросом"} | Нет | 
| 5XX | {"сообщение: Периодически повторяющаяся ошибка, необязательное сообщение"} | Да | 
Дубликаты
Нет гарантии, что один лид будет доставлен ровно один раз, поэтому веб-хук обработки лидов должен корректно обрабатывать дубликаты.