Implementation

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 {
  // Column name.
  optional string column_name = 1;

  // Column value based on column type
  oneof column_value {
    string string_value = 2;
  }
}

// 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;
  // Google click id which tracks the ad click
  optional string gcl_id;
  // Key to be used by advertiser to verify the request
  // is from google.
  optional string google_key = 5;
  // Denotes if the lead is a test lead.
  optional bool is_test = 6;

}

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).

campaign_id ID parameter of the campaign that the lead form is associated with.
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_name: 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 User_column_data.string_value content
"Full Name" User full name.
"User Email" User email.
"User Phone" User Phone in E.164 format, e.g., "+11234567890".
"Postal Code" Postal code of user.

Lead handling

Lead handlers should respond with the following HTTP codes:

HTTP Response Response body (JSON) Retriable 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.