Receive Facebook Ad Lead With Your Own Webhook (without Zapier)

facebook_leads.md

Step-by-step guide: Get your FB Lead on your Webhook

This gist was created in 2023 and is inspired from tixastronauta and eladnava tutorial.

The Facebook API changes frequently. As a result, this guide might not be accurate.

1 - Create an App

Sign up for Facebook Developer access if you haven't already, from the same account as your Facebook Ads advertising account.

Create an app and select Manage business integrations as the app purpose. If you're using Facebook Business Manager, make sure to select the right Business Manager account in the app creation form, when asked to do so.

Enable the live Mode otherwise you won't be able to access real leads but only test leads.. You will need to submit your app to Facebook for review to enable Live mode.

2 - Setting Up the Server

Here is an example in Node JS of the server you can build NodeJS Server from eladnava

But you can build the same with any language.

For this you need a GET endpoint. It need to return hub.challenge if the hub.verify_token is your custom Token

And in the same path a POST endpoint. It will get notified when a new lead come with the lead_id and the page_id. After that you will need to request the facebook Graph Api to get the lead data. For this last part you will need the token we will generate in the last part.

Note: The URL need to be in https Protocol

3 - Enabling the Lead Gen Webhook

1. Visit the Facebook Developer Center, select your app, scroll down to Webhooks and click Set Up Callback URL.
2. Paste in the https forwarding address
3. In the dropdown select Page.
4. Search for the leadgen webhook, and click Test next to it, followed by Send to My Server.
5. Verify Token: Enter CUSTOM_WEBHOOK_VERIFY_TOKEN (you may change this string for security purposes, but also remember to modify it in server.js accordingly).
6. Click Verify and Save.
7. Now your server need to pass the challenge.
8. Subscribe to the leadgen event

---

At this part we have a working app that get notified on new lead. We just need to link this app with our Page to get notified when our Page generate a new lead.

We also have to make our server retrieve the lead infos when he get notified. For these parts we need an access token.

4 - Generate a 3-Month Page Access Token

1. Go to https://developers.facebook.com/tools/explorer/ and generate a custom Token for your Application.
2. Under User or Page, select the name of your page, ensure the permissions are still there, and click Generate Access Token.
3. Add the following custom permissions which are necessary to retrieve Facebook Ads leads:

pages_show_list
ads_management
ads_read
leads_retrieval
pages_read_engagement
pages_manage_metadata
pages_manage_ads

IMPORTANT: Facebook keep changing needed permission. In step 5 it will check missing permissions, so it may be other permission you will need to add.

4. Accept the permission dialog once again.
5. Copy your Access Token. And go to https://developers.facebook.com/tools/debug/accesstoken and paste your Token.
6. Check that the Type is Page
7. If it is not is, you will have reset to go back to step 3. Most likely there is a bug that may require from you to generate the token more than once.
8. Scroll down and extend the token to 3 month (it is the maximum).
9. Click Debug and ensure the expiration is set to Never.

5 - Subscribe for the leadgen webhook event for the specific page we are advertising

To subscribe to our specific page, we need to manually post a request with the custom token.

curl -i -X POST 'https://graph.facebook.com/PAGE_ID/subscribed_apps?subscribed_fields=leadgen&access_token=ACCESS_TOKEN'

Check for a {"success": true} response.

Now let's check that your app is subscribed to your Page Lead generation.

Go to https://developers.facebook.com/tools/lead-ads-testing and select your Page. You will see your webhook subscribed at the bottom of the page. Just test the creation. You are supposed to get a request to your server.

IMPORTANT: Facebook keep changing needed permission so if you see other permissions missing, add the like in step 4 and retry

6 - Add App to CRM (if it is not)

Go to https://business.facebook.com/settings/leads-accesses/ and add access to the app as a CRM to the Page.

7 - Retrieve the lead data

Now your server get the leadgen_id, you can use it to retrieve the lead infos by your ACCESS_TOKEN.

For this just make a GET request (even with your browser) to: https://graph.facebook.com/LEADGEN_ID/?access_token=ACCESS_TOKEN

I could see the page only after adding business_management under permission.

Also, while testing, i did not receive any leads as it returned an error: "CRM access has been revoked from Lead Access Manager" Hence to get Test leads(https://developers.facebook.com/tools/lead-ads-testing/) You have to visit business.facebook.com and then under Integrations tab -> CRM -> Assign CRM -> {{ Select your facebook app }}

❗ THIS ❗

You need to add business_management to the permissions. It's stated NOWHERE in the documentation.