A Facebook lead ads webhook is a small HTTP endpoint you own, which Meta calls every time someone submits an Instant Form. The ping carries the lead identifier, the ad ID, the form ID and the Page ID, and you fetch the answers with a Graph API read. Set it up by creating a Meta app, subscribing it to the Page’s leadgen events, and answering the verification request on your server.
What the webhook gives you that a download does not
Meta keeps Instant Form leads downloadable for up to 90 days, which is fine while someone remembers to export and fatal when nobody does. The webhook removes the human step: the lead arrives within a few minutes, already carrying the identifiers that a CSV gets wrong or drops.
The identifiers are the reason to build it. A ping tells you which ad produced the lead, which is what you need to compute cost per lead per ad and to send pipeline stages back to Meta later. It also tells you which form and which Page, so two offers and two brands in one account do not blur.
What you need before the first line of code
- A Meta app, owned by the business that runs the ads.
- App Review for the lead ads permission, plus Business Verification.
- A Page admin who can grant leads access, because the token’s owner needs that permission for any lead to be readable.
- An endpoint with a valid certificate, reachable from the internet.
- Somewhere to put the lead that is not a log file.
The effort is real: Meta files webhooks among the developer routes, next to the Graph API bulk read, while middleware needs no code at all. Choose the webhook when you need the lead in your own system before it reaches the CRM, or when the CRM has no integration and you do not want a third party in the path.
The flow, step by step
- Create the app in Meta’s developer console and add the webhook product.
- Point the callback URL at your endpoint and set a verify token you keep secret.
- Subscribe the app to the Page, with the leadgen field selected.
- Answer the verification request: Meta calls your URL and expects the challenge value echoed back, so the subscription is confirmed.
- On each ping, read the body, take the lead identifier, and queue the job. Answer as fast as you can and do the work after, because a slow handler is a handler Meta retries.
- Read the lead from the Graph API with that identifier, take the answers, and write the record with the identifiers attached.
A ping looks like this, with the fields Meta documents:
{
"object": "page",
"entry": [
{
"id": "<page_id>",
"time": "<unix_time>",
"changes": [
{
"field": "leadgen",
"value": {
"leadgen_id": "<lead_id>",
"page_id": "<page_id>",
"form_id": "<form_id>",
"ad_id": "<ad_id>",
"created_time": "<unix_time>"
}
}
]
}
]
}
Treat the whole body as untrusted input. Verify the request came from Meta, check that the Page ID is one of yours, and reject anything else before you touch the database.
What the payload contains and what it does not
The ping has no name, no email and no phone number. Those come from the second call, the Graph API read on the lead identifier, which returns the answers as submitted, including any answer the person edited before sending.
That split has one practical consequence: your endpoint can receive a ping and fail the read, so you need the lead identifier stored before the read happens. Save the ping first, then read.
The two IDs to keep
- The lead ID, which is the key for sending stages back to Meta. Without it, the conversion leads goal has nothing to match on.
- The ad ID, which joins the lead to spend. This is the one a landing page gets from a URL parameter and an Instant Form gets from the webhook.
Keep the form ID too if you run more than one form per offer, and the creation time from Meta rather than from your server, so a queue delay does not distort your reporting window. The wider comparison of routes, including which CRMs store the lead ID at all, is in Facebook lead ads CRM integration.
Limits and failure modes
Meta applies a rate limit per Facebook Page, so a burst of submissions on one Page is throttled while other Pages keep flowing. Build the reader to back off and retry rather than to loop.
The token expires or gets revoked when an admin changes. Log the failure and alert on it: a webhook that stops delivering looks exactly like a campaign that stopped producing leads, and you will blame the ads first.
The pings can arrive out of order or more than once, so deduplicate on the lead identifier. Two records for one form submission inflate your lead count and double the follow-up.
Checklist before you call it done
- One real submission arrives end to end, with the answers and both identifiers.
- A duplicate ping creates no second record.
- The endpoint answers fast, and the heavy work runs after the answer.
- A nightly read by date catches anything the webhook missed.
- The lead reaches the CRM automatically, so the 90-day window never matters.
- Someone gets an alert when delivery stops.
From there, the lead is a row with a name and an ad attached. What you do next decides whether it becomes a customer: Facebook lead ads best practices covers the form and the follow-up, and Meta Pixel setup covers the browser side of the same measurement if the offer also runs on a landing page.