This guide goes through every step to a successful CRM integration using Webhooks. If you are a CRM partner or an independent developer looking to use the Webhooks feature to receieve updates about leads being created for your ads, read on.
We reference the following terms multiple times. So here is a brief description of them:
App – The facebook app which will be configured with the webhook APIRTU- Stands for Real time updates. They contain the information about the lead.Payload – Content that comes in the RTU. Synonymous to RTUEndpoint – The end point that you (client or crm partner) configures to receive RTUPings – These are the real time updates which will come through on your endpointCRM – Customer Relationship ManagementManage Pages and Ads Management permissions. There is a review process before granting these permissions. You will be notified by Facebook once it is complete or if there s more inforamtion required from you during the review.app_id, since you will need this in later steps.This step will let Facebook know that my app is interested in leadgen event
2.1 Create a webhook.php file
On your webserver, create a file called as webhooks.php. Note that, we were referencing this file in the call back url under the app domain. The file will have the following content:
<?php
$challenge = $_REQUEST['hub_challenge'];
$verify_token = $_REQUEST['hub_verify_token'];
if ($verify_token === 'abc123') {
echo $challenge;
}2.2 Make the api call to create subscription
The following API call is made with an app access token. The callback URL should be the URL to your app’s endpoint and the verify token should be what was added in webhook.php.
curl \ -F "object=page" \ -F "callback_url=https://www.yourcallbackurl.com" \ -F "fields=leadgen" \ -F "verify_token=abc123" \ -F "access_token=<APP_ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<APP_ID>/subscriptions"
If the API call is successful, it means that the app was successfully subscribed to receive leadgen RTU from Facebook. After this step you should be able to see this subscription when you navigate to the webhooks section.
We don’t send payloads to your apps every time someone fills a form and submits a lead on Facebook. Since the lead ads forms are associated with an advertiser’s Facebook page, we filter and send payloads only for leads that belong to those pages which authorized your app to receive the RTU.
Note: The client or advertiser who authorizes your app to listen to the RTU pings need to have ADMIN access on the page. Without this the subscription will not work.
From an advertiser’s perspective, this is how the flow will look like:
Once the above is complete then your app can receive rtu for the subscribed page.
Follow the steps below to achieve this flow:
3.1 Create platform.php file on your webserver
Once you have the file and the FB Login ready in the page, add the following code:
<h2>My Platform</h2>
<script>
window.fbAsyncInit = function() {
FB.init({
appId : '<YOUR_APP_ID>',
xfbml : true,
version : '<API_VERSION>'
});
};
(function(d, s, id){
var js, fjs = d.getElementsByTagName(s)[0];
if (d.getElementById(id)) {return;}
js = d.createElement(s); js.id = id;
js.src = "https://connect.facebook.net/en_US/sdk.js";
fjs.parentNode.insertBefore(js, fjs);
}(document, 'script', 'facebook-jssdk'));
function subscribeApp(page_id, page_access_token) {
console.log('Subscribing page to app! ' + page_id);
FB.api(
'/' + page_id + '/subscribed_apps',
'post',
{access_token: page_access_token, subscribed_fields: ['feed']},
function(response) {
console.log('Successfully subscribed page', response);
}
);
}
// Only works after `FB.init` is called
function myFacebookLogin() {
FB.login(function(response){
console.log('Successfully logged in', response);
FB.api('/me/accounts', function(response) {
console.log('Successfully retrieved pages', response);
var pages = response.data;
var ul = document.getElementById('list');
for (var i = 0, len = pages.length; i < len; i++) {
var page = pages[i];
var li = document.createElement('li');
var a = document.createElement('a');
a.href = "#";
a.onclick = subscribeApp.bind(this, page.id, page.access_token);
a.innerHTML = page.name;
li.appendChild(a);
ul.appendChild(li);
}
});
}, {scope: 'manage_pages'});
}
</script>
<button onclick="myFacebookLogin()">Login with Facebook</button>
<ul id="list"></ul>The above code does the following:
me/accounts edge to get all pages the user has access to.You can also use graph API to make this call:
curl -G \ -d "access_token=<ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/me/accounts"
You use the Page access token later to make the API call which will subscribe the advertisers page to your app. Please note that when making the call to retrieve all pages for the user, if a long lived access token is used, then page access token returned will never expire.
{PAGE_ID}/subscribed_apps edge. This is taking place in the subscribeApp function. The equivalent POST request is:curl \ -F "access_token=<PAGE_ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/subscribed_apps"
3.2 Verify the Subscription
To verify that your app was successfullysubscribed to receive RTU for the selected page, make the following GET API call
curl -G \ -d "access_token=<PAGE_ACCESS_TOKEN>" \ "https://graph.facebook.com/<API_VERSION>/<PAGE_ID>/subscribed_apps"
The response of this api call should contain an entry for your app. Here is a sample API call along with the response as shown in Grah Explorer.
webhooks.php for Incoming RTUsTo test if the RTU integration is working and if you are receiving pings from facebook, modify the webhooks.php file to handle the incoming pings, since this is the endpoint which wil:l receive the pings. For now we will error log it by adding the following code
$input = json_decode(file_get_contents('php://input'), true);
error_log(print_r($input, true));After the above steps, the webhook.php file should look like this:
<?php
$challenge = $_REQUEST['hub_challenge'];
$verify_token = $_REQUEST['hub_verify_token'];
if ($verify_token === 'abc123') {
echo $challenge;
}
$input = json_decode(file_get_contents('php://input'), true);
error_log(print_r($input, true))Please check our the real time integration video tutorial to see how the integration will look like.
Can we get multiple entries in one RTU?
Can we get duplicate RTU for the same lead?
leadgen_id in the incoming ping as the unique key and de-duplicate based on those.What access token should I use to subscribe the advertiser's page to my app?
The page access token of the advertisers page has expired. How can I get a long term page access token?
I went through the RTU Integration steps but I am not receiving the pings. What can I do to validate that my subscription is in place?
developers.facebook.com/apps/{APP_ID}/webhooks and see if the app is subscribed to receive the leadgen pings by checking for the presence of ‘leadgen’ under fields{PAGE_ID}/subscribed_apps edge and check to see if your app is amongst those listed in the response. This calls requires page access token of the page you are making the call against.How can I test the Lead Ads Integration without having to spend on creating a real Lead Ad?
Is there anyway to debug the webhooks integration and understand why it might be failing?