New Lead

trigger.facebook_lead

TriggerChat & messagingconnection requiredruns in-engine

Subscribes the tenant's Meta app to the Page's `leadgen` field on publish and starts one run per lead, verified against Meta's X-Hub-Signature-256.

Start a run when someone submits a Facebook lead ad's instant form on a Page you administer.

Ask about Facebook All Facebook nodes Provider API docs ↗

Connection

Required: Yes — the node will not save without one
Auth type: Bearer token
Providers: Facebook
Secret shape: {"access_token", "app_id", "app_secret"}
Resolved by: config.connection_id, else node.connection_id
Note: Three values, and they are not interchangeable. The Page access token (with pages_manage_metadata and pages_show_list, and leads_retrieval to read the answers later) subscribes the Page; the app id owns the webhook subscription; the app secret is what every delivery is signed with. Publishing also needs MANTLE_APP_PUBLIC_BASE_URL set to an https URL Meta can reach — Meta refuses a callback it cannot validate.

Configuration

1 field, 1 required. A dotted path is a nested object and name[] an array of objects — the editor renders the same tree.

Field	Type	Required	Default	Constraints	Example
page_id The numeric id of the Page running the lead ads — from the Page's About panel, not its @username. Every lead form on this Page starts a run; branch on form_id to tell them apart.	string	Yes	—	matches ^\d{5,}$	153590818059554

Example configuration

Every value below is the contract’s own example or default — nothing invented.

{
  "page_id": "153590818059554"
}

Output

One shape.

facebook lead

The lead's identifiers. Meta's notification carries ids only — read the answers with a Graph GET on leadgen_id in the next node.

Field	Type	Example
leadgen_id Meta's id for the captured lead, and the idempotency key: every retry of a delivery carries this same id, so a redelivery joins the run it already started. Pass it to a Graph GET /{leadgen_id} to read the answers — the notification itself never carries them.	string	444444444444444
page_id The Page the lead form belongs to.	string	153590818059554
form_id The instant form that was submitted. Branch on this when one Page runs several lead forms — the subscription cannot be narrowed to one.	string	655555555555555
ad_id The ad the lead came from, empty for an organic form.	string	—
adgroup_id The ad set the ad belongs to, where there is one.	string	—
created_time When Meta captured the lead, epoch seconds.	number	1717070400
created_at The same instant as an ISO-8601 UTC string, for nodes that want a date.	string	2024-05-30T12:00:00Z
value Meta's own change value, verbatim, for anything the fields above do not lift out.	object	—
payload The whole entry the change arrived in — its Page id, Meta's `time`, and every change it carried.	object	—

{
  "ad_id": "23851234567890123",
  "adgroup_id": "23851234567890456",
  "created_at": "2024-05-30T12:00:00Z",
  "created_time": 1717070400,
  "form_id": "655555555555555",
  "leadgen_id": "444444444444444",
  "page_id": "153590818059554",
  "payload": {
    "changes": [],
    "id": "153590818059554",
    "time": 1717070401
  },
  "value": {
    "ad_id": "23851234567890123",
    "adgroup_id": "23851234567890456",
    "created_time": 1717070400,
    "form_id": "655555555555555",
    "leadgen_id": "444444444444444",
    "page_id": "153590818059554"
  }
}

Notes

Meta keeps one webhook callback URL per app per object type, so one Meta app can serve only one published lead-ads workflow. A second publish is refused rather than silently repointing the first one's deliveries.
Meta validates the callback with a GET carrying hub.challenge. Mantle's provider ingress answers POST only, so registration fails with Meta's "URL couldn't be validated" until that route serves GET.
Every delivery is verified against X-Hub-Signature-256, an HMAC-SHA256 over the raw body keyed on the app secret; an unsigned or mis-signed POST is refused with 401 before any run starts.
The notification carries identifiers only. Read the submitted answers with a Graph GET on leadgen_id, which needs the leads_retrieval permission.
Unpublishing, disabling or archiving unsubscribes the Page and drops the app subscription, so a Page never keeps delivering into a dead workflow.

Related Facebook nodes

See New Lead run in a workflow.

In a technical demo we add the Facebook connection, drop the node on the canvas and let Workflow Health pre-flight it before the first real run.

Book a technical demo Talk to sales