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 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 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
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.