Facebook Leads form mapping and import lifecycle runbook

Facebook Leads form mapping and import lifecycle runbook explains how Meta leadgen webhooks, Graph API lead fetches, form field mapping, duplicate-safe person creation, owner/task routing, and mobile-safe attribution must be proven before Facebook Lead Ads are trusted for a gym.

What this page is for

Who should use it

Owner, implementation, marketing admin, sales manager, platform admin, support

Where to find it

Meta Lead Ads Testing Tool, Meta Page/Form settings, SquareOS Admin / Facebook Leads Setting, Sales CRM

Before you start

Facebook Leads form mapping and import lifecycle runbook: complete this lifecycle after Meta app/Page/webhook setup and before a gym treats Facebook Lead Ads as production-ready in SquareOS.
Facebook Leads mapping starts after connected Channel Account provider FACEBOOK_LEADS and records Page ID, Form ID, App ID, webhook verify token, app secret reference, Page access token reference, lead source name, lead channel name, owner staff user id, duplicate policy, full name field, email field, phone field, and Lead Ads Testing Tool evidence id.
Meta leadgen webhook proof requires GET challenge verification, subscribed leadgen field, POST x-hub-signature-256 validation using app secret, Page/Form match, leadgen id extraction, and Graph API lead fetch using Page access token before SquareOS creates or updates CRM records.
Graph lead fetch proof must capture leadgen id, created_time, page id or page name, form id or form name, campaign/ad identifiers when returned, field_data names and values, and safe raw payload storage in facebookLeadEvent evidence.
SquareOS field mapping must map provider field_data names to fullName, email, phone, lead source, lead channel, owner, duplicate policy, person/prospect, opportunity, follow-up task, facebookLeadEvent, and crm.facebook_lead.created.v1 outbox event.
Duplicate-safe import must search by phone and email before creating a person, attach new lead evidence to the matched or created person, prevent duplicate opportunity/task spam, and keep externalLeadId idempotent.
Owner and follow-up routing must prove assigned owner, opportunity stage, task due time, task outcome defaults, source/channel attribution, campaign/ad labels when available, and Staff app handoff to Sales CRM.
Lead Ads Testing Tool or real test form certification requires one Meta test lead per mapped form, verified signature, Graph fetch, mapped fields, duplicate policy result, person/opportunity/task ids, facebookLeadEvent id, outbox id, and owner/support sign-off.
Facebook Leads secret handling forbids exposing app secret, Page access token, webhook verify token, raw signed webhook headers, raw Graph payload with customer data, ad account credentials, or provider screenshots with private lead data in mobile screens, support tickets, analytics, or crash logs.
If Meta form fields or labels differ from the runbook, extraction row must record form field label, provider field_data name, SquareOS field, mapping owner, sample value handling, duplicate-policy decision, and verification action.

Daily workflow

Confirm the Facebook Leads Channel Account is connected and mapped to provider FACEBOOK_LEADS. The account must identify the Page, Form, Meta app, app secret reference, Page access token reference, webhook verify token, and safe/fake mode state before any live lead is imported.
Open Meta Page/Form settings and Meta Lead Ads Testing Tool. Record the Page ID, Form ID, form name, app id, ad account/campaign/ad identifiers when available, leadgen subscription state, testing tool result id, and the exact field labels shown to the prospect.
In SquareOS Admin / Facebook Leads Setting, set Facebook Page ID, Facebook Form ID, Meta App ID, app secret or secret reference, Page access token or secret reference, webhook verify token, lead source name, lead channel name, owner staff user id, duplicate policy, and field names for full name, email, and phone.
Configure form field mapping with provider field_data names, not only human-readable labels. Common fields are full_name, email, and phone_number, but Meta forms can use custom labels; every custom label must have an extraction row with sample value handling.
Run GET webhook challenge verification against GET /engagement/facebook-leads/webhook. The challenge passes only when hub.mode is subscribe and hub.verify_token matches a connected Facebook Leads channel account verify token.
Run a Meta Lead Ads Testing Tool lead or real test form submission. POST /engagement/facebook-leads/webhook must validate x-hub-signature-256 using the configured app secret before SquareOS fetches the leadgen record or creates CRM records.
Confirm the webhook change contains leadgen id, Page ID, and Form ID. SquareOS must match the connected channel account by Page/Form config before using the Page access token to fetch leadgen details from Graph API.
Confirm the Graph fetch returns leadgen id, created_time, page/form identifiers or names, field_data names/values, and campaign/ad labels when available. Store raw payload only in secure facebookLeadEvent evidence and never in mobile cache or screenshots.
Confirm SquareOS field mapping produces fullName, email, phone, lead source, lead channel, owner, duplicate policy, person/prospect, opportunity, follow-up task, facebookLeadEvent, and crm.facebook_lead.created.v1 outbox event. The pass condition must include exact record ids.
Test duplicate handling by submitting a lead with an existing phone or email. SquareOS must match or create according to duplicate policy, attach the new facebookLeadEvent evidence, and avoid duplicate opportunity/task spam for the same externalLeadId.
Sales manager verifies owner routing, opportunity stage, follow-up due time, default task outcome, source/channel attribution, campaign/ad labels where available, and that the lead appears in Sales CRM with a clear handoff for staff.
Record official source references used for the extraction row: Meta Lead Ads webhook setup documentation, leads retrieval/Graph API documentation, Lead Ads Testing Tool documentation, app secret proof/signature validation documentation, and SquareOS CRM/outbox evidence.

Watch out

Do not import leads from unsigned webhooks, unmatched Page/Form ids, manually typed leadgen ids, or stale Testing Tool screenshots.
Do not assume Meta form labels are stable. If a marketer edits the form, re-run field mapping QA and update the extraction row before campaign launch.
Do not store app secret, Page access token, webhook verify token, raw x-hub-signature-256, raw Graph payload, customer field_data, or private lead screenshots in mobile screens, support tickets, analytics, or crash logs.
Do not let mobile replay Facebook lead webhooks, change mappings, mutate dead letters, or certify provider setup. Mobile can show read-only attribution and staff can follow up on backend-created tasks/opportunities.
Do not certify one form and assume another form, Page, campaign, or ad set is covered. Each production form needs its own mapping evidence and test lead proof.
Do not create manual duplicate prospects when a signed lead import is delayed. Inspect webhook/dead-letter and existing facebookLeadEvent evidence first.

Use the left menu to open related pages in Start Here.
Use Ask Docs for questions that are already covered in this public documentation.