Meta Lead Ads

Lead sources

Meta Lead Ads starts a run for every new lead on a Facebook Page. Meta sends a notification that carries only ids; the Webhook Trigger node then reads the lead from Meta with the Page's access token and emits one row per lead.

When to use it

• New leads from a Facebook lead form go into a CRM, a database or an email.
• Each lead needs to arrive within seconds, not on a schedule.

There are two ways to set it up:

• Your own Meta app. You create the app in Meta, paste its app secret into DataLug and copy DataLug's callback URL and verify token into the app.
• The DataLug app. You sign in with Facebook and pick the Page. This option appears only when it is available on your account.

Both need a webhook in Manage Account > Webhooks, a Meta Lead Ads connection for the Page, and a Webhook Trigger node set to Meta leads.

What you need

For your own Meta app:

• A Meta app you manage, with its App secret from App settings > Basic.
• A Page access token for the Page, from that app, with the leads_retrieval permission.
• The Page ID, the numeric ID of the Facebook Page.

For the DataLug app:

• A Facebook login that manages the Page.
• Consent to the permissions Meta asks for when you sign in:
  • pages_show_list
  • pages_read_engagement
  • pages_manage_metadata
  • leads_retrieval
  • ads_management

Together they let DataLug list your Pages, subscribe its app to a Page and read each lead.

Connect

Your own Meta app

Create the webhook.

1. In Manage Account > Webhooks, select New webhook, enter a name and set Signature to Meta Lead Ads.
2. Paste the app secret into Meta app secret.
3. Leave Verify token (Optional) blank to generate one, or enter your own: 16 to 256 characters with no spaces.
4. Press Create webhook. Copy the Callback URL and the Verify token. A generated verify token is shown once.

Set up the Meta app.

1. In your Meta app, open Webhooks and select the Page object.
2. Paste the callback URL and the verify token, then verify and save. Meta checks the verify token against DataLug before it saves. The webhook in Manage Account > Webhooks then shows Challenge passed.
3. Subscribe to the leadgen field.
4. Subscribe the app to the Page with the Graph API subscribed_apps call and the leadgen field.

See Meta's Webhooks for Lead Ads guide for the app side.

Add the connection. In Connections, add a Meta Lead Ads connection.

The connection form lists its steps on the left. Open any step from that list. The Environments step holds the values that differ per environment.

Test connection is in the form footer. Beside it, Test against picks Base, the connection as saved, or an environment, whose values are applied first.

Field	Step	What to enter
Page access token	Authentication	The Page token from your Meta app. Required. Stored encrypted and never shown again.
Page ID	Connection	The numeric ID of the Facebook Page. Required.
Page name (Optional)	Connection	A name to show in DataLug.

Test connection reads the Page with its token. Save the connection once the test passes. Scheduled health checks run the same test. A failed test says which of these it is:

• The Page access token is invalid or expired.
• The token is missing a permission. Leads need leads_retrieval.
• The token belongs to another Page.
• Meta could not be reached.

The test cannot see leads_retrieval on its own. A token that reads the Page but lacks it passes the test and fails on the first lead read.

Rotate the app secret. Press Rotate on the webhook. Enter the new app secret, and a new verify token if you want one, then press Save settings. The previous secret and verify token keep working for 24 hours, or until you press Revoke old secret.

The DataLug app

Shown as Meta Lead Ads (DataLug app) under Signature when it is available on your account. There is no app secret to enter: DataLug's Meta app signs the requests.

1. In Manage Account > Webhooks, select New webhook, enter a name, set Signature to Meta Lead Ads (DataLug app) and press Create webhook.
2. Open the webhook in Manage Account > Webhooks, press Pages, then Connect with Facebook. Sign in to Facebook in the window that opens and allow the permissions above.
3. Your Facebook Pages are listed. Press Connect beside a Page. DataLug subscribes its app to the Page and creates a Meta Lead Ads connection for it.

Remove releases the Page and deletes its connection. Sign out of Facebook ends the Facebook sign-in in DataLug.

On a Private Agent, leads from the DataLug app run only on an agent that reports its version. On an older agent the delivery stays Accepted with the reason Private Agent needs an update, is retried every 15 minutes, and moves to Dead letter when its retries run out. Update the agent, then press Replay.

Set up the node

1. Add a Webhook Trigger node and bind it to the webhook.
2. Press Configure on the node. Under Output, set Rows from each delivery to Meta leads.
3. Pick the Page's connection under Meta Lead Ads connection.

Raw payload stays the default. With it, the node emits Meta's notification as sent, ids only.

What arrives

One row per lead:

• The notification's own fields, such as leadgen_id, page_id, form_id and ad_id.
• lead_created_time, when the lead was submitted.
• One column per form question, named as in the lead form. A question whose name matches a field above is prefixed field_.

A notification with several leads gives several rows. The leadgen_id is the event id, so a lead Meta sends twice runs once. Every accepted request is answered 200.

Limits

• One connection holds one Page's token. Use one connection per Page.
• A Page can be connected to the DataLug app from one DataLug account at a time.
• Only an Owner or Admin can create, change or delete Meta Lead Ads connections.
• A DataLug app connection cannot be duplicated or reconfigured, and it is deleted with Remove under Pages, not from Connections.
• The DataLug app's webhook has no Test button and no Rotate, and its signature setting cannot be changed. Create a new webhook to use your own app instead.

Troubleshooting

What you see	What to do
Meta does not save the callback URL	Check that the verify token in Meta matches the one DataLug showed.
The run fails with a message about a different Page	The lead's Page is not the connection's Page. Pick the right connection on the node.
Runs fail after weeks of working	The Page token expired or was revoked. Replace it in the connection.
This Page is already connected to a DataLug account.	Another DataLug account holds the Page. Remove it there first.
Meta refused the request (code N).	Meta declined the call. Sign in with Facebook again and check the Page permissions.
Release the Page under Meta Lead Ads before deleting this connection.	Press Pages on the webhook and Remove the Page.
The node emits ids only	Rows from each delivery is still Raw payload. Set it to Meta leads.

Related

• Meta Lead Ads with a generic webhook: the same intake from the general webhook settings.
• Webhook Trigger node
• Receive a webhook from any system
• Connections