Esquema de POST
La solicitud POST que se envía al webhook estará en formato JSON con el siguiente esquema:
Carga útil de Proto del 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];
}
Descripción del campo
| Campo | Descripción | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Es una cadena única que identifica un cliente potencial determinado.
Control de recomendaciones: Úsalo para anular la duplicación de los clientes potenciales que se reciben. Será único en todos los formularios. Cuando informes problemas relacionados con un cliente potencial específico, se requerirá este ID. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Es la versión de la API a la que pertenece este esquema de clientes potenciales. Se usará cuando se migre a un esquema nuevo y se puede ignorar por el momento. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Es el ID único de cada formulario configurado en Google Ads. El producto actual permite adjuntar un formulario a nivel de la campaña (en lugar de adjuntarlo a nivel del grupo de anuncios o del anuncio).
Implicaciones: Los clientes potenciales solo se pueden segmentar a nivel de Los clientes deben usar un número entero de 8 bytes para procesar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
Es el ID de la campaña de Google Ads o el ID de la línea de pedido (Display & Video 360) del formulario de clientes potenciales adjunto.
Los clientes deben usar un número entero de 8 bytes para procesar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
El ID del grupo de anuncios de Google Ads se usa para distinguir el grupo de anuncios específico en la campaña. (Solo disponible para los clientes potenciales de los anuncios de video y discovery)
Los clientes deben usar un número entero de 8 bytes para procesar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
El ID de la creatividad de Google Ads se usa para distinguir la creatividad específica en el grupo de anuncios. (Solo disponible para los clientes potenciales de los anuncios de video y discovery)
Los clientes deben usar un número entero de 8 bytes para procesar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
ID de clic de Google, un parámetro único que se usa para hacer un seguimiento de cada clic en un anuncio | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Es una clave que configura el anunciante con cada formulario.
Sugerencia de procesamiento: Antes de procesar un cliente potencial recibido a través de un webhook, validar |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Este campo tiene semántica "opcional". Si el valor es verdadero, trata este cliente potencial como cliente potencial de prueba. Si el valor es falso o si el campo no está presente, trata este cliente potencial como un cliente potencial de producción válido. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Es una tupla clave-valor repetida que transmite los datos enviados por el usuario.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Este campo solo se propaga para las campañas de máximo rendimiento.
Indica el ID del contenedor que contiene el formulario de clientes potenciales.
Los clientes deben usar un número entero de 8 bytes para procesar. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Indica la etapa del cliente potencial en el momento de la entrega. Este campo es útil para hacer un seguimiento de la etapa del embudo o el estado de conversión de un cliente potencial. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Indica la fecha y hora en que el usuario envió el formulario. Se representa en formato ISO-8601. Ex- 2024-09-26T12:30:00Z |
Campos no reconocidos y compatibilidad con versiones futuras
Para garantizar que la integración de tu webhook siga siendo sólida y se pueda adaptar a las mejoras futuras, es una práctica recomendada estándar diseñar tu analizador de JSON para que ignore correctamente cualquier campo dentro de la carga útil del webhook que tu sistema no consuma o reconozca de forma explícita.
Recomendación clave: Configura tu lógica de análisis de JSON para que solo procese los campos que necesitas específicamente para tu aplicación. No escribas código que espere un conjunto fijo de campos o que falle si hay campos nuevos e inesperados en la carga útil.
Por qué es importante:
- Compatibilidad con versiones futuras: En futuras actualizaciones, Google puede agregar campos nuevos y opcionales a la carga útil del webhook para proporcionar datos más enriquecidos o nuevas funciones. Si tu analizador es demasiado estricto (p.ej., falla en propiedades desconocidas), tu integración podría fallar cuando Google lance este tipo de cambios que no interrumpen la integración.
- Mantenimiento simplificado: Al enfocarte solo en los puntos de datos que usas de forma activa, el código de integración sigue siendo más simple y fácil de mantener.
La mayoría de las bibliotecas modernas de análisis de JSON ofrecen opciones para ignorar las propiedades desconocidas de forma predeterminada o se pueden configurar para que lo hagan.
Manejo de clientes potenciales
Los controladores de clientes potenciales deben responder con los siguientes códigos HTTP:
| Respuesta HTTP | Cuerpo de la respuesta (JSON) | ¿Se puede reintentar el error? |
|---|---|---|
200 |
{} | N/A |
4XX |
{"message: Free form error text, describing what was wrong with request"} | No |
5XX |
{"message: Intermittent retraible error optional message"} | Sí |
Duplicados
No se garantiza que un solo cliente potencial se entregue exactamente una vez, por lo que el webhook de procesamiento de clientes potenciales debe controlar los duplicados de forma correcta.