Schéma POST
La requête POST envoyée au webhook sera au format JSON avec le schéma suivant :
Charge utile proto du 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];
}
Description du champ
| Champ | Description | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Chaîne unique qui identifie un prospect donné.
Recommandation de traitement : utilisez cette option pour dédupliquer les prospects reçus. Cette valeur sera unique pour tous les formulaires. Cet ID sera requis lorsque vous signalerez des problèmes liés à un prospect spécifique. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
Version de l'API à laquelle appartient ce schéma de prospects. Cette valeur sera utilisée lors de la migration vers un nouveau schéma. Vous pouvez l'ignorer pour le moment. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
ID unique pour chaque formulaire configuré dans Google Ads. Le produit actuel permet d'associer un formulaire au niveau de la campagne (au lieu de l'associer au niveau du groupe d'annonces ou de l'annonce).
Implications : les prospects ne peuvent être segmentés qu'au niveau Les clients doivent utiliser un entier de 8 octets pour le traitement. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
ID de la campagne Google Ads ou de l'élément de campagne (Display & Video 360) du formulaire pour prospects associé.
Les clients doivent utiliser un entier de 8 octets pour le traitement. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
L'ID de groupe d'annonces Google Ads permet de distinguer le groupe d'annonces spécifique dans la campagne. (Disponible uniquement pour les prospects générés par les annonces vidéo et Discovery)
Les clients doivent utiliser un entier de 8 octets pour le traitement. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
L'ID de création Google Ads permet de distinguer la création spécifique dans le groupe d'annonces. (Disponible uniquement pour les prospects générés par les annonces vidéo et Discovery)
Les clients doivent utiliser un entier de 8 octets pour le traitement. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
L'ID de clic Google est un paramètre unique utilisé pour suivre chaque clic sur une annonce. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
Clé configurée par l'annonceur avec chaque formulaire.
Recommandation de traitement : avant de traiter un prospect reçu via un webhook, validez |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
Ce champ est facultatif. Si la valeur est "true", ce prospect est considéré comme un prospect de test. Si la valeur est "false" ou si le champ n'est pas présent, traitez ce prospect comme un prospect de production valide. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
Tuple clé-valeur répété transmettant les données envoyées par l'utilisateur.
|
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
Ce champ n'est renseigné que pour les campagnes Performance Max.
Il s'agit de l'ID du conteneur contenant le formulaire pour prospects.
Les clients doivent utiliser un entier de 8 octets pour le traitement. |
|||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
Cela indique l'étape du prospect au moment de sa transmission. Ce champ est utile pour suivre l'étape de l'entonnoir ou l'état de conversion d'un prospect. | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
Il s'agit du code temporel auquel l'utilisateur a envoyé le formulaire. Elle est représentée au format ISO-8601. Ex- 2024-09-26T12:30:00Z |
Champs non reconnus et compatibilité ascendante
Pour que votre intégration de webhook reste robuste et puisse s'adapter aux futures améliorations, il est recommandé de concevoir votre analyseur JSON de manière à ignorer correctement tous les champs de la charge utile du webhook que votre système ne consomme ni ne reconnaît explicitement.
Recommandation clé : Configurez votre logique d'analyse JSON pour traiter uniquement les champs dont vous avez spécifiquement besoin pour votre application. N'écrivez pas de code qui s'attend à un ensemble fixe de champs ou qui échouerait si de nouveaux champs inattendus sont présents dans la charge utile.
Pourquoi est-ce important ?
- Compatibilité ascendante : Google peut ajouter de nouveaux champs facultatifs à la charge utile du webhook lors de futures mises à jour afin de fournir des données plus riches ou de nouvelles fonctionnalités. Si votre analyseur est trop strict (par exemple, s'il échoue sur les propriétés inconnues), votre intégration peut être interrompue lorsque Google déploie de tels changements non destructifs.
- Maintenance simplifiée : en vous concentrant uniquement sur les points de données que vous utilisez activement, le code d'intégration reste plus simple et plus facile à gérer.
La plupart des bibliothèques d'analyse JSON modernes proposent des options permettant d'ignorer les propriétés inconnues par défaut ou peuvent être configurées pour le faire.
Gestion des prospects
Les gestionnaires de prospects doivent répondre avec les codes HTTP suivants :
| Réponse HTTP | Corps de la réponse (JSON) | Erreur récupérable ? |
|---|---|---|
200 |
{} | N/A |
4XX |
{"message: Free form error text, describing what was wrong with request"} | Non |
5XX |
{"message: Intermittent retraible error optional message"} | Oui |
Doublons
Il n'est pas garanti qu'un seul lead soit transmis exactement une fois. Par conséquent, le webhook de gestion des leads doit gérer les doublons de manière appropriée.