Table of Contents
Webhook Integration for Search Lead Forms
A webhook is an API that enables you to send lead data to your CRM system in real-time. To set it up, you will need to add a webhook URL and key to your lead form extension. You may need to do some configuration within your CRM, like Salesforce , system to generate the URL and key.
The URL is the delivery path: after the user submits a lead form, an HTTP POST request is sent to the configured URL, allowing the lead data to go directly into the CRM system. The key is used for validating the leads sent.
Webhook Integration Instructions
- Sign into your Google Ads account.
- In the page menu on the left, click Campaigns .
-
Click the plus button
, and then select
New campaign
.
- In the goals section, select Leads .
- Under “Campaign type,” select Search.
- Click Continue .
- Enter your campaign settings.
- In the “Ad extensions” list, select Lead form extension .
- Fill in details about your extension and your lead form.
- Under “Create form submission message”, click on Lead Delivery Option . This will show the “Manage your leads with a webhook” field.
- Enter the Webhook URL and Key.
-
Click
Send test data
to view testing states and results.
Check your data management system to confirm that you have received the test data. - After filling in the required steps, click Add to campaign .
, and then select
New campaign
.
Error States
Depending on your initial actions after adding webhooks, you may receive error states.
- Error state A is when users save the form without sending test data (successfully).
- Error state B is data that is not sent.
- Error state C is data sent without Google receiving a response.
- Error state D is data sent, but Google receives an incorrect response (HTTP 200).
- Success state is data sent, and Google receives a correct response.
To set it up, you will need to add a webhook URL and key to your lead form. The URL is the delivery path: after the user submits a lead form, an HTTP POST request is sent to the configured URL, allowing the lead data to go directly into the CRM system. The key is used for validating the leads sent.
Lead Form Webhook Implementation
| 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.
|
Testing Webhook Implementation
Using API Tester
Once you have configured a URL you wish to use for lead handling, test to see if it can handle a request constructed on api_tester_sample . Replace advertiser_lead_handler_url with your own URL and verify if your lead handler is working as expected.
Using the webhook validation in the form builder UI (recommended)
Once the webhook is set up in Google Ads, we recommend you test if your CRM is set up correctly using the test functionality. Otherwise, you may not receive the lead data in your CRM system.
When constructing your lead form in Google Ads, you will see a test button below the webhook set-up:
Note that the set-up interface may look different if you are setting up a lead form on Search.
Once you hit the test button, a sample webhook request is sent to your configured webhook endpoint and a result is displayed. If the request was received successfully by your CRM and the HTML response status code from your system was
200
, you will see a green status message:
To complete the test in such a case, please verify that your CRM has correctly received and parsed the sample payload. Without performing this step there is no guarantee that the webhook is working properly.
A sample of the payload that is sent is shown below. The actual request will contain only fields that were selected in the form:
Form fields selected in the example: Name, Phone, Email
Lead type: Test payload sent by webhook testing UI
{
"lead_id"
:
"MTM4Nzc4MzM2MzpsZWFkX2lkOjE1NTkwODQ5NjQ4MzU"
,
"campaign_id"
:
123456
,
"gcl_id"
:
"CKbai8W4xN4CFcoFrwkdyHEByw"
,
"user_column_data"
:
[
{
"column_name"
:
"Full Name"
,
"string_value"
:
"FirstName LastName"
},
{
"column_name"
:
"User Phone"
,
"string_value"
:
"1-650-555-0123"
},
{
"column_name"
:
"User Email"
,
"string_value"
:
"test@example.com"
}],
"api_version"
:
"1.0"
,
"form_id"
:
123456789
,
"Google_key"
:
"testkey"
,
"is_test"
:
true
}
Please note that
form_id
field value will be set to the actual id of your form if you are performing a test on a form that is already saved. For unsaved forms, a dummy value will be provided.
Using curl command
You can use curl from your Mac or Linux command line.
- Choose a sample payload from Samples , and modify if required.
-
Store it in a file (e.g.,
request.txt) on your machine. -
Run the following command on your command line:
$ curl - v - X POST -- header "Content-Type:application/json" - d @request . txt https : // webhook_u
Webhook Integrations Recommendations
The API tester is an approximation for live lead handling. Google recommends taking the following steps when going live for the first time:
-
Once you have used the API tester to validate lead handling, set up a campaign with a small budget and add the webhook URL and key.
- Important : If the webhook integration was not set up correctly, you will not lose leads. You can download leads via CSV download.
- Turn on the campaign.
- Validate that the leads are handled correctly by your CRM.
-
Are the leads handled successfully?
- Yes : Great! You can now increase your budget and create multiple campaigns and forms.
- No : Please read through this documentation to troubleshoot. If you need help, visit the Google Support Page.
-
Once you have used the API tester to validate lead handling, set up a campaign with a small budget and add the webhook URL and key.
Contact Us Today!