Implementação

Esquema POST

A solicitação POST enviada para o webhook será no formato JSON com o seguinte esquema:

Payload Proto do webhook

// 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];
}

Descrição do campo

Campo Descrição
lead_id String exclusiva que identifica um lead.

Como lidar com recomendações:use essa opção para eliminar duplicações de leads que são recebidos. Ele será exclusivo em todos os formulários. Ao informar problemas relacionados a um lead específico, esse ID será necessário.

api_version Versão da API à qual este esquema de lead pertence. Isso será usado ao migrar para um novo esquema e pode ser ignorado por enquanto.
form_id ID exclusivo para cada formulário configurado no Google Ads. O produto atual permite anexar um formulário com um nível de campanha (em vez de anexar no nível do grupo de anúncios ou do anúncio).

Implicações:os leads só podem ser divididos no nível form_id, ou seja, na campanha.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

campaign_id O ID da campanha do Google Ads ou do item de linha (Display & Video 360) do formulário de lead anexado.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

adgroup_id O ID do grupo de anúncios do Google Ads é usado para distinguir o grupo de anúncios específico na campanha. (Disponível apenas para leads de anúncios Discovery e em vídeo)

Os clientes precisam usar um número inteiro de 8 bytes para processar.

creative_id O ID do criativo do Google Ads é usado para distinguir o criativo específico no grupo de anúncios. (Disponível apenas para leads de anúncios Discovery e em vídeo)

Os clientes precisam usar um número inteiro de 8 bytes para processar.

gcl_id ID de clique do Google, um parâmetro exclusivo usado para acompanhar cada clique em um anúncio.
google_key Uma chave configurada pelo anunciante com cada formulário.

Como processar a recomendação:antes de processar um lead recebido por webhook, validar google_key é o mesmo que configurar no Google Ads para ter mais confiança de que o lead é válido. Mantenha essa chave confidencial e atualize no Google Ads se houver motivos para acreditar que ela vazou para muitas pessoas.

is_test Este campo tem semântica "opcional". Se o valor for verdadeiro, trate esse lead como um lead de teste. Se o valor for falso ou se o campo não estiver presente, trate esse lead como um lead de produção válido.
user_column_data Uma tupla de chave-valor repetida que transmite dados enviados pelo usuário.
  • user_column_data.column_id: tipo de dados enviado pelo usuário.
  • User_column_data.column_value: para cada tipo de dados, um tipo de valor será preenchido dependendo do tipo de dados. Todos os nossos tipos de dados atuais têm o valor de user_column_data.string_value.
  • user_column_data.column_name: texto legível por humanos do tipo de dados enviado pelo usuário. Esse campo nem sempre é preenchido. Use column_id .
user_column_data.column_id conteúdo de User_column_data.string_value user_column_data.column_name (descontinuado)
"FULL_NAME" Nome completo do usuário. "Nome completo"
"FIRST_NAME" Nome do usuário, "Nome"
"LAST_NAME" Sobrenome do usuário, "Sobrenome"
"EMAIL" E-mail do usuário "E-mail do usuário"
"PHONE_NUMBER" Número de telefone do usuário no formato E.164, por exemplo, "+11234567890". "User Phone"
"POSTAL_CODE" Código postal do usuário. "CEP"
"COMPANY_NAME" Nome da empresa do usuário. "Nome da empresa"
"JOB_TITLE" Cargo do usuário. "Cargo"
"WORK_EMAIL" E-mail de trabalho do usuário. "E-mail de trabalho"
"WORK_PHONE" Número de telefone do trabalho do usuário. "Telefone de trabalho"
"STREET_ADDRESS" Endereço do usuário. "Endereço"
"CIDADE" Cidade do usuário. "Cidade"
"REGION" Região do usuário. "Região"
"COUNTRY" País do usuário. "País"
"VEHICLE_MODEL" Em qual modelo você tem interesse? N/A
"VEHICLE_TYPE" Em que tipo de veículo você tem interesse? N/A
"PREFERRED_DEALERSHIP" Selecione sua concessionária preferida N/A
"VEHICLE_PURCHASE_TIMELINE" Quando você planeja comprar um veículo? N/A
"VEHICLE_CONDITION" Qual é o estado do veículo que você procura? N/A
"VEHICLE_OWNERSHIP" Você tem carro? "N/A"
"VEHICLE_PAYMENT_TYPE" Em qual opção de propriedade de veículo você tem interesse? N/A
"COMPANY_SIZE" Qual é o porte da sua empresa? N/A
"ANNUAL_SALES" Qual é seu volume de vendas anual? N/A
"YEARS_IN_BUSINESS" Há quantos anos sua empresa atua na área? N/A
"JOB_DEPARTMENT" Em qual departamento seu cargo se encaixa? N/A
"JOB_ROLE" Qual é seu cargo? N/A
"EDUCATION_PROGRAM" Em qual programa você tem interesse? N/A
"EDUCATION_COURSE" Em qual curso você tem interesse? N/A
"PRODUTO" Em qual produto você tem interesse? N/A
"SERVICE" Em qual serviço você tem interesse? N/A
"OFFER" Em qual oferta você tem interesse? N/A
"CATEGORY" Em qual categoria você tem interesse? N/A
"PREFERRED_CONTACT_METHOD" Selecione uma forma de contato N/A
"PREFERRED_LOCATION" Selecione um local N/A
"PREFERRED_CONTACT_TIME" Qual é o melhor horário para entrar em contato com você? N/A
"PURCHASE_TIMELINE" Quando você tem intenção de fazer uma compra? N/A
"YEARS_OF_EXPERIENCE" Quantos anos de experiência você tem? N/A
"JOB_INDUSTRY" Você trabalha em qual setor? N/A
"LEVEL_OF_EDUCATION" Qual é seu nível de escolaridade? N/A
"PROPERTY_TYPE" Que tipo de imóvel você está procurando? N/A
"REALTOR_HELP_GOAL" Para que você precisa da ajuda de um corretor? N/A
"PROPERTY_COMMUNITY" Em qual comunidade você tem interesse? N/A
"PRICE_RANGE" Qual faixa de preço você está procurando? N/A
"NUMBER_OF_BEDROOMS" Quantos quartos você gostaria de ter? N/A
"FURNISHED_PROPERTY" Você está procurando um imóvel mobiliado? N/A
"PETS_ALLOWED_PROPERTY" Você está procurando imóveis que permitem animais de estimação? N/A
"NEXT_PLANNED_PURCHASE" Qual é o próximo produto que você planeja comprar? N/A
"EVENT_SIGNUP_INTEREST" Você gostaria de se inscrever em um evento? N/A
"PREFERRED_SHOPPING_PLACES" Onde você gosta de fazer compras? N/A
"FAVORITE_BRAND" Qual é sua marca preferida? N/A
"TRANSPORTATION_COMMERCIAL_LICENSE_TYPE" Que tipo de licença comercial válida você tem? N/A
"EVENT_BOOKING_INTEREST" Você tem interesse em agendar um evento? N/A
"DESTINATION_COUNTRY" Qual é seu país de destino? N/A
"DESTINATION_CITY" Qual é sua cidade de destino? N/A
"DEPARTURE_COUNTRY" Qual é seu país de partida? N/A
"DEPARTURE_CITY" Qual é sua cidade de partida? N/A
"DEPARTURE_DATE" Qual é sua data de partida? N/A
"RETURN_DATE" Qual é sua data de retorno? N/A
"NUMBER_OF_TRAVELERS" Com quantas pessoas você está viajando? N/A
"TRAVEL_BUDGET" Qual é o orçamento da sua viagem? N/A
"TRAVEL_ACCOMMODATION" Onde você gostaria de ficar durante sua viagem? N/A
asset_group_id Esse campo só é preenchido para campanhas Performance Max. Indica o ID do contêiner que contém o formulário de lead.

Os clientes precisam usar um número inteiro de 8 bytes para processar.

lead_stage Isso indica a fase do lead no momento da entrega. Esse campo é útil para acompanhar o estágio do funil / status de conversão de um lead.
lead_submit_time Indica o carimbo de data/hora em que o usuário enviou o formulário. Ele é representado no formato ISO-8601. Ex- 2024-09-26T12:30:00Z

Campos não reconhecidos e compatibilidade com versões anteriores

Para garantir que a integração do webhook permaneça robusta e possa se adaptar a futuras melhorias, é uma prática recomendada padrão projetar o analisador JSON para ignorar todos os campos no payload do webhook que o sistema não consuma ou reconheça explicitamente.

Recomendação importante:configure a lógica de análise JSON para processar apenas os campos necessários para o app. Não escreva código que espere um conjunto fixo de campos ou que falhe se campos novos e inesperados estiverem presentes no payload.

Por que isso é importante:

  • Compatibilidade futura:o Google pode adicionar novos campos opcionais ao payload do webhook em atualizações futuras para fornecer dados mais completos ou novos recursos. Se o analisador for muito rigoroso (por exemplo, falhar em propriedades desconhecidas), a integração poderá falhar quando essas mudanças não importantes forem lançadas pelo Google.
  • Manutenção simplificada:ao se concentrar apenas nos pontos de dados que você usa ativamente, o código de integração fica mais simples e fácil de manter.

A maioria das bibliotecas de análise JSON modernas oferece opções para ignorar propriedades desconhecidas por padrão ou pode ser configurada para fazer isso.

Gestão de leads

Os gerenciadores de leads precisam responder com os seguintes códigos HTTP:

Resposta HTTP Corpo da resposta (JSON) Erro que permite uma nova tentativa?
200 {} N/A
4XX {"message: Free form error text, describing what was wrong with request"} Não
5XX {"message: Intermittent retraible error optional message"} Sim

Cópias

Não há garantia de que um único lead será entregue exatamente uma vez. Portanto, o webhook responsável por processar leads precisa processar duplicatas corretamente.