POST 스키마
webhook에 전송되는 POST 요청은 다음 스키마가 포함된 JSON 형식입니다.
웹훅 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 | 특정 리드를 식별하는 고유 문자열입니다. 처리 권장사항: 수신된 리드의 중복을 제거하는 데 사용합니다. 이 ID는 모든 양식에서 고유합니다. 특정 리드와 관련된 문제를 신고할 때 이 ID가 필요합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| api_version | 이 리드 스키마가 속한 API 버전입니다. 새 스키마로 이전할 때 사용되며 지금은 무시해도 됩니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| form_id | Google Ads에 구성된 각 양식의 고유 ID입니다. 현재 제품에서는 광고 그룹 또는 광고 수준에서 연결하는 대신 캠페인 수준으로 양식을 연결할 수 있습니다. 의미: 리드는  클라이언트는 처리할 때 8바이트 정수를 사용해야 합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| campaign_id | 첨부된 리드 양식의 Google Ads 캠페인 ID 또는 광고 항목 ID (Display & Video 360)입니다. 클라이언트는 처리할 때 8바이트 정수를 사용해야 합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adgroup_id | Google Ads 광고 그룹 ID는 캠페인의 특정 광고 그룹을 구별하는 데 사용됩니다. (동영상 및 디스커버리 광고에서 발생한 리드에만 사용할 수 있음) 클라이언트는 처리할 때 8바이트 정수를 사용해야 합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| creative_id | Google Ads 광고 소재 ID는 광고 그룹에서 특정 광고 소재를 구분하는 데 사용됩니다. (동영상 및 디스커버리 광고에서 발생한 리드에만 사용할 수 있음) 클라이언트는 처리할 때 8바이트 정수를 사용해야 합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gcl_id | 광고의 각 클릭을 추적하는 데 사용되는 고유한 매개변수인 Google 클릭 ID | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| google_key | 광고주가 각 양식에 구성한 키입니다. 처리 권장사항: webhook을 통해 수신된 리드를 처리하기 전에  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_test | 이 필드는 '선택사항' 시맨틱을 갖습니다. 값이 true이면 이 리드를 테스트 리드로 처리합니다. 값이 false이거나 필드가 없으면 이 리드를 유효한 프로덕션 리드로 처리합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| user_column_data | 사용자가 제출한 데이터를 전송하는 반복되는 키-값 튜플입니다. 
 
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| asset_group_id | 이 필드는 실적 최대화 캠페인에 대해서만 채워집니다.
      리드 양식이 포함된 컨테이너 ID를 나타냅니다. 클라이언트는 처리할 때 8바이트 정수를 사용해야 합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_stage | 리드 전송 시 리드 단계를 나타냅니다. 이 필드는 리드의 유입경로 단계 / 전환 상태를 추적하는 데 유용합니다. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_submit_time | 사용자가 양식을 제출한 타임스탬프를 나타냅니다. ISO-8601 형식으로 표시됩니다. 예: 2024-09-26T12:30:00Z | 
인식되지 않는 필드 및 향후 호환성
웹훅 통합이 강력하게 유지되고 향후 개선사항에 적응할 수 있도록 하려면 시스템에서 명시적으로 사용하거나 인식하지 않는 웹훅 페이로드 내 필드를 적절하게 무시하도록 JSON 파서를 설계하는 것이 표준 권장사항입니다.
주요 권장사항: 애플리케이션에 특히 필요한 필드만 처리하도록 JSON 파싱 로직을 구성합니다. 고정된 필드 세트를 예상하거나 페이로드에 예상치 못한 새 필드가 있는 경우 실패하는 코드를 작성하지 마세요.
중요한 이유:
- 전방 호환성: Google은 향후 업데이트에서 더 풍부한 데이터 또는 새로운 기능을 제공하기 위해 webhook 페이로드에 선택적 새 필드를 추가할 수 있습니다. 파서가 너무 엄격하면 (예: 알 수 없는 속성에서 실패) Google에서 이러한 비중단 변경사항을 출시할 때 통합이 중단될 수 있습니다.
- 간소화된 유지관리: 실제로 사용하는 데이터 포인트에만 집중하면 통합 코드를 더 간단하고 쉽게 유지할 수 있습니다.
대부분의 최신 JSON 파싱 라이브러리는 기본적으로 알 수 없는 속성을 무시하는 옵션을 제공하거나 그렇게 구성할 수 있습니다.
리드 처리
리드 핸들러는 다음 HTTP 코드로 응답해야 합니다.
| HTTP 응답 | 응답 본문 (JSON) | 재시도 가능한 오류인가요? | 
|---|---|---|
| 200 | {} | 해당 사항 없음 | 
| 4XX | {"message: 요청에 문제가 무엇인지 설명하는 자유 형식의 오류 텍스트"} | 아니요 | 
| 5XX | {"message: Intermittent retraible error optional message"} | 예 | 
중복
단일 리드가 정확히 한 번만 전송된다고 보장할 수 없으므로 리드 처리 웹훅은 중복을 적절하게 처리해야 합니다.