Receiving Facebook Leads on a Webhook

1 - Create an App

Head over to developer.facebook.com and create an App

2 - Setup the webhook

On your server, create a facebook webhook that will handle facebook calls. Then create a "leadgen" webhook on you App: https://developers.facebook.com/docs/graph-api/webhooks/v2.11

3 - Get an access token

Get lifetime access token to App (I asked for the following permissions: manage_pages, publish_pages, publish_actions, public_profile)

Note: Token should now be listed in: https://developers.facebook.com/tools/accesstoken/

4 - Subscribe App to Page

Subscribe App to Page using your access token

curl \
-F "access_token=<ACCESS_TOKEN>" \
"https://graph.facebook.com/v2.11/<PAGE_ID>/subscribed_apps"

5 - Handling Webhook requests

Whenever a Lead is generated you'll receive a request on your facebook webhook with the following body:

{
   "object":"page",
   "entry":[
      {
         "id":"51044240199134611",
         "time":1447342027,
         "changes":[
            {
               "field":"leadgen",
               "value":{
                  "adgroup_id":0,
                  "ad_id":0,
                  "created_time":1447342026,
                  "leadgen_id":55459717045641545,
                  "page_id":516540199134611,
                  "form_id":551111744595541
               }
            }
         ]
      }
   ]
}

Now, grab the lead using the leadgen_id value:

curl -G \
  -d 'access_token=<ACCESS_TOKEN>' \
  https://graph.facebook.com/v2.11/<LEADGEN_ID>

Sample output:

{
   "created_time": "2015-11-12T15:27:06+0000",
   "id": "555971704561545",
   "field_data": [
      {
         "name": "full_name",
         "values": [
            "James Oak"
         ]
      },
      {
         "name": "email",
         "values": [
            "james.oak\u0040example.org"
         ]
      },
      {
         "name": "date_of_birth",
         "values": [
            "April 19, 1987"
         ]
      },
      {
         "name": "gender",
         "values": [
            "male"
         ]
      }
   ],
   "is_tcpa_compliant": false
}