Schema POST
La richiesta POST inviata all'webhook sarà in formato JSON con lo schema seguente:
Payload del protocollo 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];
}
Descrizione del campo
| Campo | Descrizione | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| lead_id | Stringa univoca che identifica un determinato lead. Consiglio per la gestione:utilizza questa opzione per eliminare i duplicati dei lead ricevuti. Questo valore sarà univoco in tutti i moduli. Quando segnali problemi relativi a un lead specifico, questo ID sarà obbligatorio. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| api_version | Versione dell'API a cui appartiene questo schema lead. Verrà utilizzato durante la migrazione a un nuovo schema e per il momento può essere ignorato. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| form_id | ID univoco per ogni modulo configurato in Google Ads. Il prodotto attuale consente di collegare un modulo a livello di campagna (anziché a livello di gruppo di annunci o di annuncio). Implicazioni:i lead possono essere suddivisi solo a livello di  I client devono utilizzare un numero intero di 8 byte per l'elaborazione. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| campaign_id | L'ID campagna o elemento pubblicitario Google Ads (Display & Video 360) del
      modulo per i lead allegato. I client devono utilizzare un numero intero di 8 byte per l'elaborazione. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| adgroup_id | L'ID gruppo di annunci Google Ads viene utilizzato per distinguere il gruppo di annunci specifico nella campagna. (disponibile solo per i lead provenienti dagli annunci video e discovery) I client devono utilizzare un numero intero di 8 byte per l'elaborazione. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| creative_id | L'ID creatività Google Ads viene utilizzato per distinguere la creatività specifica nel gruppo di annunci. (disponibile solo per i lead provenienti da annunci video e discovery) I client devono utilizzare un numero intero di 8 byte per l'elaborazione. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| gcl_id | ID clic Google, un parametro univoco utilizzato per monitorare ogni clic su un annuncio. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| google_key | Una chiave configurata dall'inserzionista con ogni modulo. Consiglio per la gestione: prima di elaborare un lead ricevuto tramite webhook, la convalida di  | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| is_test | Questo campo ha una semantica "facoltativa". Se il valore è true, tratta questo lead come lead di test. Se il valore è falso o se il campo non è presente, considera questo lead come lead di produzione valido. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| user_column_data | Una tupla chiave-valore ripetuta che trasmette i dati inviati dall'utente. 
 
 | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| asset_group_id | Questo campo viene compilato solo per le campagne Performance Max.
      Indica l'ID del contenitore che contiene il modulo per i lead. I client devono utilizzare un numero intero di 8 byte per l'elaborazione. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_stage | Indica la fase del lead al momento della sua invio. Questo campo è utile per monitorare la fase della canalizzazione / lo stato di conversione di un lead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
| lead_submit_time | Indica il timestamp in cui l'utente ha inviato il modulo. È rappresentato in formato ISO-8601. Da 26-09-2024T12:30:00Z | 
Campi non riconosciuti e compatibilità futura
Per garantire che l'integrazione del webhook rimanga solida e possa adattarsi ai miglioramenti futuri, è una best practice standard progettare lo scanner JSON in modo da ignorare in modo elegante eventuali campi all'interno del payload del webhook che il sistema non consuma o riconosce esplicitamente.
Consiglio chiave:configura la logica di analisi del JSON in modo da elaborare solo i campi richiesti specificamente per la tua applicazione. Non scrivere codice che preveda un insieme fisso di campi o che non vada a buon fine se nel payload sono presenti campi nuovi e imprevisti.
Perché è importante:
- Compatibilità futura:Google potrebbe aggiungere nuovi campi facoltativi al payload del webhook in aggiornamenti futuri per fornire dati più completi o nuove funzionalità. Se il tuo parser è troppo rigido (ad es. non funziona con proprietà sconosciute), l'integrazione potrebbe non funzionare quando queste modifiche non incidono vengono implementate da Google.
- Manutenzione semplificata:concentrandoti solo sui punti dati che utilizzi attivamente, il codice di integrazione rimane più semplice e facile da gestire.
La maggior parte delle librerie di analisi JSON moderne offre opzioni per ignorare le proprietà sconosciute per impostazione predefinita o può essere configurata in questo modo.
Gestione dei lead
I gestori dei lead devono rispondere con i seguenti codici HTTP:
| Risposta HTTP | Corpo della risposta (JSON) | Errore non irreversibile? | 
|---|---|---|
| 200 | {} | N/D | 
| 4XX | {"message: Free form error text, describing what was wrong with request"} | No | 
| 5XX | {"message: Intermittent retraible error optional message"} | Sì | 
Duplicati
Non è garantito che un singolo lead venga inviato esattamente una volta, pertanto l'webhook per la gestione dei lead deve gestire i duplicati in modo appropriato.