POST schema
The POST request sent to webhook will be in JSON format with the following schema:
Webhook Proto payload
// 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];
}
Field description
Field | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
lead_id |
Unique string which identifies a given lead.
Handling recommendation: Use this to dedupe leads which are received. This will be unique across all forms. When reporting issues related to a specific lead, this id will be required. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
api_version |
API version which this lead schema belongs to. This will be used when migrating to a new schema, and can be ignored for now. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
form_id |
Unique ID for each form configured in Google Ads. Current product allows
attaching a form with a campaign level (vs. attaching at ad group or ad
levels).
Implications: Leads can be sliced only at Clients need to use 8 bytes integer to process. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
campaign_id |
The Google Ads campaign ID or line item ID (Display & Video 360) of the
attached lead form.
Clients need to use an 8-byte integer to process. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
adgroup_id |
The Google Ads ad group ID is used to distinguish the specific
ad group in the campaign. (Available for leads from video and discovery
ads only)
Clients need to use an 8-byte integer to process. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
creative_id |
The Google Ads creative ID is used to distinguish the specific
creative in the ad group. (Available for leads from video and discovery
ads only)
Clients need to use an 8-byte integer to process. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
gcl_id |
Google click ID, a unique parameter used to track each click of an ad. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
google_key |
A key configured by the advertiser with each form.
Handling recommendation: Before processing a lead received over
webhook, validating |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
is_test |
This field has "optional" semantic. If value is true, treat this lead as test lead. If value is false or if field is not present, treat this lead as valid production lead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
user_column_data |
A repeated key-value tuple transmitting user submitted data.
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
asset_group_id |
This field is only populated for Performance-Max campaigns.
This denotes the container id that contains the lead form.
Clients need to use an 8-byte integer to process. |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_stage |
This denotes the lead stage at the time of lead delivery. This field is helpful in tracking the funnel stage / conversion status of a lead. | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
lead_submit_time |
This denotes the timestamp at which user submitted the form. It is represented in ISO-8601 format. Ex- 2024-09-26T12:30:00Z |
Unrecognized fields and forward compatibility
To ensure your webhook integration remains robust and can adapt to future enhancements, it is a standard best practice to design your JSON parser to gracefully ignore any fields within the webhook payload that your system does not explicitly consume or recognize.
Key Recommendation: Configure your JSON parsing logic to only process the fields you specifically require for your application. Don't write code that expects a fixed set of fields or that would fail if new, unexpected fields are present in the payload.
Why this is important:
- Forward Compatibility: Google may add new, optional fields to the webhook payload in future updates to provide richer data or new features. If your parser is too strict (e.g., fails on unknown properties), your integration could break when such non-breaking changes are rolled out by Google.
- Simplified Maintenance: By only focusing on the data points you actively use, your integration code remains simpler and easier to maintain.
Most modern JSON parsing libraries offer options to ignore unknown properties by default or can be configured to do so.
Lead handling
Lead handlers should respond with the following HTTP codes:
HTTP Response | Response body (JSON) | Retryable error? |
---|---|---|
200 |
{} | N/A |
4XX |
{"message: Free form error text, describing what was wrong with request"} | No |
5XX |
{"message: Intermittent retraible error optional message"} | Yes |
Duplicates
A single lead is not guaranteed to be delivered exactly once, hence lead handling webhook should handle duplicates gracefully.