Webhook Facebook App Events API

Overview

Submit an HTTP request to Facebook to track one or more in-app conversions. Event data is expressed as a JSON encoded string. See the Facebook App Events API for more details.

API call example:

curl \
  -F "event=CUSTOM_APP_EVENTS" \
  -F "advertiser_id=1111-1111-1111-1111" \
  -F "advertiser_tracking_enabled=1" \
  -F "application_tracking_enabled=1" \
  -F "custom_events=[{\"_eventName\":\"fb_mobile_purchase\",
                      \"_valueToSum\":55.22,
                      \"_logTime\":1367017882,
                      \"fb_currency\":\"GBP\",
                    }]" \
  "https://graph.facebook.com/API_VERSION/APP_ID/activities"

The provided curl example (with the -F option) implies the request uses a POST method and its body is “multipart/form-data” content type. Let’s break down the whole request into separate components that can be configured in the Webhook.

1. API endpoint/URL

https://graph.facebook.com/API_VERSION/APP_ID/activities

In the example the URL has placeholder values for the API version and the APP_ID. These could probably be hard-coded into the URL, but for demonstration purposes we’ll use a URL Template to create this component using dynamic values.

2. Simple form field values

  event = CUSTOM_APP_EVENTS
  advertiser_id = 1111-1111-1111-1111
  advertiser_tracking_enabled = 1
  application_tracking_enabled = 1

These key/value pairs are simple form fields that can be mapped using Custom Values in the Body Data section.

3. JSON value

custom_events = [{ "_eventName"  : "fb_mobile_purchase",
                   "_valueToSum" : 55.22,
                   "_logTime"    : 1367017882,
                   "fb_currency" : "GBP",
                }]

This particular field named “custom_events” has a more complicated value, a JSON string. To recreate this value in the Webhook we’ll use Template Variables and a Template.

Webhook settings

Method field

Set to “POST”.

URL field

Set to {{url_template}}.

URL can either be hard coded (with embedded api version and app ID) or template based. The latter approach is taken to allow greater flexibility with data layer attributes. See templates section below.

Body content type

Select option multipart/form-data.

Body data

Set name/value pairs for each field from the example request. Notice that the value for custom_events is the name of the Template we create, events_template.

Parameter values are custom/static values in this example, but can easily be provided as dynamic Data Layer Attributes.

Template variables

Set name/value pairs to be referenced and replaced in the Templates.

Templates

You will create two templates, one for the URL and one for the JSON value to be assigned to the custom_events parameter. Notice that the Templates make use of the Template Variables using the curly brackets syntax.

It’s important to understand that this template is based on the “eventSums.value” variable which is populated by a Set of String Attribute. This is an array Attribute so the template will create a section for the prefix of the template variable name we used (in this case “eventSums”).

url_template:

https://graph.facebook.com/{{apiVersion}}/{{appId}}/activities

events_template:

 [ 
 {{#eventSums}} 
 {     
  "_eventName"  : "{{name}}",     
  "_valueToSum" : {{value}},     
  "_logTime"    : {{logTime.toTimestamp}},     
  "fb_currency" : "{{currency}}"
}{{#iter.hasNext}}, {{/iter.hasNext}}
 {{/eventSums}} 
 ] 

Rendered remplates

The Templates get rendered and their content used wherever they are referenced in the Webhook settings (in this example, the URL and the custom_events field in the Body Data).

Notice that the _valueToSum parameter receives the values from the Set of Strings attribute.

url_template:

https://graph.facebook.com/v2.6/12345/activities

events_template:

[     
 {         
  "_eventName"  : "fb_mobile_purchase",         
  "_valueToSum" : 0.99,         
  "_logTime"    : 1468358987,         
  "fb_currency" : "USD"     
  },     
  {         
    "_eventName"  : "fb_mobile_purchase",         
    "_valueToSum" : 4.99,         
    "_logTime"    : 1468358987,         
    "fb_currency" : "USD"     
  } 
]