Skip to main content

Facebook Lead Ads Webhook

Facebook Lead Ads are a specialized type of Facebook ad that allows you to collect information from prospects without needing to send them to a separate page. When someone clicks on your lead ad, they're prompted to fill out a form that's prepopulated with their Facebook credentials, where possible. You can then use this information to follow up with potential customers or add them to your lead lists.

With Tonkean, you can monitor Facebook Lead Ads as a data source to collect campaigns, lead gens, and other entities. Setup for this data source using OAuth requires the same procedure as other native data sources.

Additionally, you can set up a webhook connection that sends lead gen updates from your Facebook app directly to Tonkean. Setting up this webhook requires additional configuration, which is detailed in the sections below.

We recommend that only admins set up the webhook option—knowledge of REST API clients and API troubleshooting experience is required.

Prerequisites

Create a Facebook Ads Data Source in Tonkean and Copy the Webhook URL

First, add a new data source for Facebook Lead Ads and copy the webhook URL.

  1. Connect Facebook Ads as a native cloud application.

    In the Add New Data Source window, select the Facebook Ads data source, not the Facebook Lead Ads data source.

  2. In the Set Update Data Source window, select the relevant account you want to connect, then select OK.

  3. In your newly-created Facebook Ads data source, select Connections in the data source configuration panel. The Connections screen displays.

    tonk_connections_select.png

  4. In the Facebook Ads connected instance, select Edit. The Set Up Data Source window displays.

    tonk_fb_ads_edit_select.png

  5. Select Create Facebook Ads Webhook Endpoint. The endpoint URL displays.

    set_up_data_source_create_webhook_endpoint.png

  6. Copy the webhook endpoint URL and save it in a separate document.

    set_up_data_source_webhook_endpoint_url.png

  7. When finished, select OK.

Create a New App in Meta for Developers

Next, create a new app in Meta that can send events to Tonkean using the webhook connection.

  1. Navigate to Meta for Developers.

  2. Create a new app. Make sure to configure the below settings as described:

    1. When asked which use case to add to your app, select Other.

    2. Select the Business app type.

    3. Provide an app name, such as Tonkean Lead Gen.

Add App ID and Set Up Webhook

Configure the app and webhook.

Add App ID

Retrieve the Meta app ID and secret token for use later in the process.

  1. In your newly-created app, select Settings > Basic in the sidenav. The Basic Settings screen displays.

  2. Copy the App ID and App secret values and save these in a separate document.

  3. In the sidenav, select Settings > Advanced. The Advanced Settings screen displays.

  4. Scroll down to the Advertising Accounts section and in the Authorized ad accounts IDs field, paste in your App ID. When finished, select Save changes in the lower right.

Set Up Webhook

Set up the webhook that allows your newly-created app to communicate with Tonkean.

  1. In the sidenav, select Add Product.

  2. Scroll down to the Webhooks card and select Set up.

  3. Select the dropdown at the top of the screen and select Page, then select Subscribe to this object. The Edit Page subscription window displays.

  4. In the Callback URL field, enter the webhook endpoint URL you created in Tonkean.

  5. In the Verify token field, enter any string.

    The verify token is not used by Tonkean but is required in the Meta app.

  6. Select Verify and save in the lower right. The Edit Page subscription window closes and the Page objects display.

  7. Scroll down to the leadgen object and select Subscribe. A success message displays indicating that you've subscribed to the leadgen object.

Add App Permissions and Grant Access

With the webhook set up, you must add permissions to your app and grant access to the app on the relevant page.

  1. Navigate to the Graph API Explorer.

  2. In the Meta App dropdown, select your app.

  3. In the User or Page dropdown, select Get User Access Token. A new Access Token displays.

  4. In the Permissions field, add the following permissions one at a time:

    1. read_insights

    2. pages_show_list

    3. ads_management

    4. ads_read

    5. business_management

    6. leads_retrieval

    7. pages_read_engagement

    8. pages_manage_metadata

    9. pages_manage_ads

  5. In the Access Token field, select Generate Access Token. A login window displays where you confirm the account you want to add these permissions for.

  6. Follow the steps provided in the login window to complete the connection.

    Once complete, a success message displays in the login window: {Username} has been connected to {app name}

    You must have an existing page to complete the connection.

  7. Select Got it in the lower right to close the login window. The newly-generated Access Token displays.

  8. Copy the Access Token and save it in a separate document.

Generate a Long-Lived Page Access Token

A long-lived page access token helps avoid future problems with verification when the Facebook Lead Ads data source updates.

Before submitting the requests below to generate the long-lived page access token, retrieve the following values you generated or saved earlier in the process:

In the Graph Explorer, submit the following API requests, replacing each instance of the ID and token values with your app's unique values:

  1. Select the GET method and enter oauth/access_token?grant_type=fb_exchange_token&client_id={app-id}&client_secret={app-secret}&fb_exchange_token={access-token} and select Submit. The response returns the long-lived user access token.

    Make sure when pasting the queries into the Graph Explorer that special characters are not automatically escaped, such as the ampersand "&" being replaced with "&".

  2. Copy the long-lived user access token into a separate document.

  3. Select the GET method and enter me?fields=id&access_token={long-lived-user-access-token} and select Submit. The response returns the user ID.

  4. Copy the returned user ID into a separate document.

  5. Select the GET method and enter {user-id}/accounts?access_token={long-lived-user-access-token}. The response returns the data object, containing two needed fields:

    • access_token - Long-lived page access token

    • id - Page ID

      This is the id value nested one level below the data object (displayed below the relevant page name), not the id value contained within the category_list object.

    graph_exp_long_lived_page_access_token.png

  6. Copy the access token and ID into a separate document.

    The access token returned in this response is not the access token you generated earlier in the process.

Install the App on your Page

With the long-lived page access token and relevant page ID, install the app on your page:

  1. Select the POST method and enter {page_id}/subscribed_apps?subscribed_fields=leadgen.

  2. In the Access Token field, enter the long-lived page access token return in step #6 of Generate a Long-Lived Page Access Token.

  3. With the request configured and the long-lived page access token entered, select Submit. A success message is returned.

    If an error occurs, use the generated error message to troubleshoot the problem. Common mistakes include pasting in the long-lived user access token instead of the long-lived page access token.

Your app is successfully installed on your page and you're ready to test.

Test the Webhook

With your app and webhook configured, you can test the webhook with any existing forms you have in your Meta for Developers instance.

  1. Navigate to the Lead Ads Testing Tool.

  2. Select the relevant Page and Form you want to test.

    You must have forms to test the webhook. To learn more about creating Lead Ads forms, see How to Create a Lead Ad from Your Facebook Page.

  3. Beside the Form dropdown, select Preview form. The form displays in a new window.

  4. Select Create lead. This activates the webhook, sending the test data from the form to Tonkean.

  5. Navigate to the Facebook Ads data source in Tonkean and select View Data in the data source configuration panel. The Facebook Ads| View Data screen displays.

  6. Select the Entity dropdown and select Lead Gens.

  7. Confirm the test lead gen you created in the Lead Ads Testing Tool displays.

Your Facebook Lead Ads webhook is configured and ready to start sending leads to Tonkean.

In this section: