Google Ads

How Do I set up Webhook integration for Search Lead Forms in Google Ads?

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

  1. Sign into your Google Ads account.
  2. In the page menu on the left, click Campaigns.
  3. Click the plus button   , and then select New campaign.
  4. In the goals section, select Leads.
  5. Under “Campaign type,” select Search.
  6. Click Continue.
  7. Enter your campaign settings.
  8. In the “Ad extensions” list, select Lead form extension.
  9. Fill in details about your extension and your lead form.
  10. Under “Create form submission message”, click on Lead Delivery Option. This will show the “Manage your leads with a webhook” field.
  11. Enter the Webhook URL and Key.
  12. Click Send test data to view testing states and results.
    Check your data management system to confirm that you have received the test data.
  13. After filling in the required steps, click Add to 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.

webhook Integration

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.

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

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.

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:

Google Ads Webhook Leads form

 

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.

  1. Choose a sample payload from Samples, and modify if required.
  2. Store it in a file (e.g., request.txt) on your machine.
  3. 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:

    1. 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.
    2. Turn on the campaign.
    3. Validate that the leads are handled correctly by your CRM.
    4. 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.
     

Contact Us Today!


Call Now