Implementation

    • POST requests to the webhook will be in JSON format, adhering to a specific schema for user lead data.

    • The JSON payload includes fields for lead identification, user-submitted data, form and campaign details, and verification keys.

    • User-submitted data is contained within user_column_data , using column_id and string_value to represent the data type and its value.

    • Webhook payload processing should ignore unrecognized fields for forward compatibility.

    • Lead handlers should use the lead_id for deduplication and respond with specific HTTP codes indicating success or different types of errors.

    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 
  
 UserLeadColum 
 n 
 Da 
 ta 
  
 { 
  
 // Human-readable text of the field type (e.g.: Full Name,  What is your 
  
 // preferred dealership?). This field might not always be populated. 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 colum 
 n 
 _ 
 na 
 me 
  
 = 
  
 1 
 ; 
  
 // Column value based on column type 
  
 o 
 ne 
 o 
 f 
  
 colum 
 n 
 _value 
  
 { 
  
 s 
 tr 
 i 
 n 
 g 
  
 s 
 tr 
 i 
 n 
 g_value 
  
 = 
  
 2 
 ; 
  
 } 
  
 // Column ID. Populated for all types of fields. (e.g.: FULL_NAME) 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 colum 
 n 
 _id 
  
 = 
  
 3 
 ; 
 } 
 // Message to construct webhook JSON payload 
 message 
  
 WebhookLead 
  
 { 
  
 // Unique ID to represent lead 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 lead_id 
  
 = 
  
 1 
 ; 
  
 // User inputted data per column 
  
 repea 
 te 
 d 
  
 UserLeadColum 
 n 
 Da 
 ta 
  
 user_colum 
 n 
 _da 
 ta 
  
 = 
  
 2 
 ; 
  
 // API version 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 api_versio 
 n 
  
 = 
  
 3 
 ; 
  
 // Form ID to which lead belonged to. 
  
 op 
 t 
 io 
 nal 
  
 i 
 nt 
 64 
  
 f 
 orm_id 
  
 = 
  
 4 
 ; 
  
 // Campaign ID that the lead form is associated with 
  
 op 
 t 
 io 
 nal 
  
 i 
 nt 
 64 
  
 campaig 
 n 
 _id 
  
 = 
  
 5 
 ; 
  
 // Key to be used by advertiser to verify the request 
  
 // is from Google. 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 google_key 
  
 = 
  
 6 
 ; 
  
 // Denotes if the lead is a test lead. 
  
 op 
 t 
 io 
 nal 
  
 bool 
  
 is_ 
 test 
  
 = 
  
 7 
 ; 
  
 // Click ID for the lead submission. 
  
 op 
 t 
 io 
 nal 
  
 s 
 tr 
 i 
 n 
 g 
  
 gcl_id 
  
 = 
  
 8 
 ; 
  
 // Adgroup ID which generated the lead. 
  
 op 
 t 
 io 
 nal 
  
 i 
 nt 
 64 
  
 adgroup_id 
  
 = 
  
 9 
 ; 
  
 // Creative ID which generated the lead. 
  
 op 
 t 
 io 
 nal 
  
 i 
 nt 
 64 
  
 crea 
 t 
 ive_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. 
  
 i 
 nt 
 64 
  
 asse 
 t 
 _group_id 
  
 = 
  
 11 
 ; 
  
 // Lead stage at the time of delivery. 
  
 s 
 tr 
 i 
 n 
 g 
  
 lead_s 
 ta 
 ge 
  
 = 
  
 12 
  
 [ 
 (da 
 ta 
 pol.sema 
 nt 
 ic_ 
 t 
 ype) 
  
 = 
  
 ST_NOT_REQUIRED 
 ] 
 ; 
  
 // Lead submit time in ISO-8601 format. Ex- 2024-09-26T12:30:00Z 
  
 s 
 tr 
 i 
 n 
 g 
  
 lead_submi 
 t 
 _ 
 t 
 ime 
  
 = 
  
 13 
  
 [ 
 (da 
 ta 
 pol.sema 
 nt 
 ic_ 
 t 
 ype) 
  
 = 
  
 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 form_id level (i.e., at campaign level).

    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 google_key is the same as configuring in Google Ads in order to have more confidence that the lead is valid. Keep this key confidential and update in Google Ads if there is a reason to believe that this has leaked widely.

    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.
    • user_column_data.column_id : Data type submitted by the user.
    • User_column_data.column_value : For each data type, there will be a value type populated depending on data type. All our current data types have the value of user_column_data.string_value .
    • user_column_data.column_name : Human-readable text of the data type submitted by the user. This field might not always be populated, use column_id instead.
    user_column_data.column_id User_column_data.string_value content user_column_data.column_name (Deprecated)
    "FULL_NAME"
    		 User full name. "Full Name"
    "FIRST_NAME"
    		 User first name. "First Name"
    "LAST_NAME"
    		 User last name. "Last Name"
    "EMAIL"
    		 User email. "User Email"
    "PHONE_NUMBER"
    		 User Phone in E.164 format , e.g., "+11234567890" . "User Phone"
    "POSTAL_CODE"
    		 Postal code of user. "Postal Code"
    "COMPANY_NAME"
    		 Company name of user. "Company Name"
    "JOB_TITLE"
    		 Job title of user. "Job Title"
    "WORK_EMAIL"
    		 Work email of user. "Work Email"
    "WORK_PHONE"
    		 Work phone of user. "Work Phone"
    "STREET_ADDRESS"
    		 Street address of user. "Street Address"
    "CITY"
    		 City of user. "City"
    "REGION"
    		 Region of user. "Region"
    "COUNTRY"
    		 Country of user. "Country"
    "VEHICLE_MODEL"
    		 Which model are you interested in? N/A
    "VEHICLE_TYPE"
    		 Which type of vehicle are you interested in? N/A
    "PREFERRED_DEALERSHIP"
    		 Select your preferred dealership N/A
    "VEHICLE_PURCHASE_TIMELINE"
    		 When do you plan on purchasing a vehicle? N/A
    "VEHICLE_CONDITION"
    		 What type of vehicle condition are you interested in? N/A
    "VEHICLE_OWNERSHIP"
    		 Do you own a vehicle? "N/A"
    "VEHICLE_PAYMENT_TYPE"
    		 What vehicle ownership option are you interested in? N/A
    "COMPANY_SIZE"
    		 What size is your company? N/A
    "ANNUAL_SALES"
    		 What is your annual sales volume? N/A
    "YEARS_IN_BUSINESS"
    		 How many years have you been in business? N/A
    "JOB_DEPARTMENT"
    		 What is your job department? N/A
    "JOB_ROLE"
    		 What is your job role? N/A
    "EDUCATION_PROGRAM"
    		 Which program are you interested in? N/A
    "EDUCATION_COURSE"
    		 Which course are you interested in? N/A
    "PRODUCT"
    		 Which product are you interested in? N/A
    "SERVICE"
    		 Which service are you interested in? N/A
    "OFFER"
    		 Which offer are you interested in? N/A
    "CATEGORY"
    		 Which category are you interested in? N/A
    "PREFERRED_CONTACT_METHOD"
    		 Select your preferred method of contact N/A
    "PREFERRED_LOCATION"
    		 Select your preferred location N/A
    "PREFERRED_CONTACT_TIME"
    		 What is the best time to contact you? N/A
    "PURCHASE_TIMELINE"
    		 When are you looking to make a purchase? N/A
    "YEARS_OF_EXPERIENCE"
    		 How many years of work experience do you have? N/A
    "JOB_INDUSTRY"
    		 What industry do you work in? N/A
    "LEVEL_OF_EDUCATION"
    		 What is your highest level of education? N/A
    "PROPERTY_TYPE"
    		 What type of property are you looking for? N/A
    "REALTOR_HELP_GOAL"
    		 What do you need a realtor's help with? N/A
    "PROPERTY_COMMUNITY"
    		 What community are you interested in? N/A
    "PRICE_RANGE"
    		 What price range are you looking for? N/A
    "NUMBER_OF_BEDROOMS"
    		 How many bedrooms are you looking for? N/A
    "FURNISHED_PROPERTY"
    		 Are you looking for a fully furnished property? N/A
    "PETS_ALLOWED_PROPERTY"
    		 Are you looking for properties that allow pets? N/A
    "NEXT_PLANNED_PURCHASE"
    		 What is the next product you plan to purchase? N/A
    "EVENT_SIGNUP_INTEREST"
    		 Would you like to sign up for an event? N/A
    "PREFERRED_SHOPPING_PLACES"
    		 Where are you interested in shopping? N/A
    "FAVORITE_BRAND"
    		 What is your favorite brand? N/A
    "TRANSPORTATION_COMMERCIAL_ LICENSE_TYPE"
    		 Which type of valid commercial license do you have? N/A
    "EVENT_BOOKING_INTEREST"
    		 Are you interested in booking an event? N/A
    "DESTINATION_COUNTRY"
    		 What is your destination country? N/A
    "DESTINATION_CITY"
    		 What is your destination city? N/A
    "DEPARTURE_COUNTRY"
    		 What is your departure country? N/A
    "DEPARTURE_CITY"
    		 What is your departure city? N/A
    "DEPARTURE_DATE"
    		 What is your departure date? N/A
    "RETURN_DATE"
    		 What is your return date? N/A
    "NUMBER_OF_TRAVELERS"
    		 How many people are you traveling with? N/A
    "TRAVEL_BUDGET"
    		 What is your travel budget? N/A
    "TRAVEL_ACCOMMODATION"
    		 Where do you want to stay during your travel? N/A
    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.
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: