Leads, CRMs and follow-up

How do I set up a Facebook lead ads webhook for my own system?

A lead ads webhook sends leadgen_id, ad ID and form ID to your endpoint within minutes; you then read the answers from the Graph API and store both IDs.

Published

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

  1. Create the app in Meta’s developer console and add the webhook product.
  2. Point the callback URL at your endpoint and set a verify token you keep secret.
  3. Subscribe the app to the Page, with the leadgen field selected.
  4. Answer the verification request: Meta calls your URL and expects the challenge value echoed back, so the subscription is confirmed.
  5. 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.
  6. 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

  1. One real submission arrives end to end, with the answers and both identifiers.
  2. A duplicate ping creates no second record.
  3. The endpoint answers fast, and the heavy work runs after the answer.
  4. A nightly read by date catches anything the webhook missed.
  5. The lead reaches the CRM automatically, so the 90-day window never matters.
  6. 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.

Questions on this topic

All questions on this topic →

FAQ

What does the webhook actually send?+

A ping with the lead identifier, the ad ID, the form ID, the Facebook Page ID and the creation time. The answers themselves are not in the ping: you read the lead from the Graph API with the identifier you just received.

How fast is a lead ads webhook?+

Meta describes it as near real time and warns that a ping can take up to a few minutes. That is still fast enough to call a lead while the ad is fresh, and it is far ahead of a scheduled bulk read.

Why does the webhook need App Review and Business Verification?+

The lead ads permission is a restricted one, so Meta wants an app with a reviewed use case and a verified business before it will deliver leads to your endpoint. Plan for that review time before you promise a launch date to a client.

What happens if my endpoint is down?+

The delivery is retried, and anything you miss is still readable for up to 90 days through a Graph API read by date. Build a nightly reconciliation run anyway, because a retry that keeps failing is silent.

Do I still need a CRM if I have a webhook?+

The webhook is plumbing, not a CRM. It gets the lead to your server; the CRM is where the sales team works it and where stages come from. Send the lead onward with its identifiers attached, and keep the lead ID in a field you can query.

Ready to find out what
converts, for real?

Free to start.

Start free →