Introduction

The Graph API supports real-time updates to enable your application using Facebook to subscribe to changes in data in Facebook. Your application can then cache data and receive updates, rather than polling Facebook’s servers. Caching data and using this API can improve the reliability of your application and decrease its load times.

Whenever a subscribed change occurs, Facebook makes an HTTP POST request to a callback URL you specify with a list of changes. Your application will generally receive notification of the change within a couple of minutes of its occurrence.

Here are the steps to set up a subscription:

1. Set up an endpoint URL that receives both HTTP GET (for subscription verification) and POST (for actual change data) requests from Facebook.
2. Make a POST to the graph API url https://graph.facebook.com/<app-id>/subscriptions to subscribe, and be ready to handle the verification request.

---

Objects

You can currently subscribe to updates for these types of objects:

• user – Get notifications about particular fields and connections corresponding to user nodes in the Graph API.
• permissions – Get notifications when your users change the permissions they afford your applications. The available permissions are listed in the scope table in the permissions API reference.
• page - Get notifications when pages that have installed your application as a Tab change their public properties. Note that the page topic is only used for subscribing to changes to public attributes of the page (like name, category, picture etc). This is the same information that is returned by the Graph API call https://graph.facebook.com/<PAGE_ID>.

Note: Not all properties and connections of the user object can be subscribed to.

You can subscribe to all of the User object properties except verified.

Here are the list of User connections to which you can subscribe: feed, friends, activities, interests, music, books, movies, television, likes, checkins.

You can't subscribe to these User connections yet: home, tagged, posts, photos, albums, videos, groups, notes, events, inbox, outbox, updates, accounts.

We will add support for more properties and connections in the future. If you are interested, please check back on this page at later time for updates.

---

Subscription APIs

There are three things you can do by sending a request to https://graph.facebook.com/<app-id>/subscriptions?access_token=...

The distinguishing difference among them is simply whether you send an HTTP POST, GET, or DELETE request.

• Add or modify a subscription (POST)
• List each of your subscribed objects and their subscribed fields (GET)
• Delete subscriptions (DELETE)

In all cases, you must send an OAuth Application access_token. App access tokens are obtained using your App ID and your App Secret:

https://graph.facebook.com/oauth/access_token?client_id=<APP_ID>&client_secret=<APP_SECRET>&grant_type=client_credentials

Add or Modify a Subscription

To setup a subscription, send a POST with the following parameters.

• object - The type of the object you want to receive updates about, e.g. user, page or permissions. You will receive updates about all objects of that type which are connected to your application. For example, for user, you will get updates about all users who have auth'd your app. For page, you will get updates about the pages which have added your application as a tab.
• fields - A comma-separated list. This is a list of properties or connections on the specified object. For example, to monitor changes to user's name, picture, friends, and News Feed, you would specify "name,picture,friends,feed"
• callback_url - A callback URL to which Facebook will post subscription updates.
• verify_token - A subscriber-provided opaque token that will be echoed back in the verification request to assist the subscriber in identifying which subscription request is being verified. This is from the PubSubHubbub spec.

When Facebook received this POST this request, we will perform a GET on your callback URL to ensure it is valid and correctly setup to receive realtime updates. See below for information on Subscription Verification. The callback URL must respond with the correct response for the subscription to be created successfully.

Note that an application can only have one subscription for each object type. If a subscription already exists for this object type, then the newly posted data replaces any existing data.

List Subscriptions

Doing a GET returns JSON-encoded content that lists your subscriptions, up to one per object type.

[
  {
    "object": "user",
    "callback_url": "http://www.xyz.com/sub_endpoint?xyz_token=123",
    "fields": ["email", "friends", "name", "picture"],
    "active": true
  },
  {
    "object": "permissions",
    "callback_url": "http://www.xyz.com/sub_endpoint?xyz_token=123",
    "fields": ["email", "read_stream"],
    "active": true
  },
  {
    "object": "errors",
    "callback_url": "http://www.otherdomain.com/sub_endpoint?xyz_token=456",
    "fields": ["canvas"],
    "active": true
  }
]

Delete Subscriptions

Sending a DELETE request deletes all of your subscriptions. If you specify an object parameter, it will only delete the corresponding object's subscription.

---

Your Callback Server

Your callback server must handle two types of requests.

Facebook servers will make a single HTTP GET to your callback URL when you try to add or modify a subscription. After a successful subscription, Facebook servers will notify your server of changes by issuing HTTP POST requests to the same URL.

Subscription Verification

Before subscription addition/modification can complete, Facebook servers will make an HTTP GET to your callback URL with the following parameters:

• hub.mode - The string subscribe is passed in this parameter
• hub.challenge - A random string
• hub.verify_token - The verify_token value you passed to Facebook

The end point should first verify the verify_token value is what you passed to Facebook, then return the hub.challenge value. This verification technique prevents malicious apps from using the real-time feature as tool for distributed denial-of-service (DDoS) attacks.

Note for PHP developers: In PHP, dots and spaces in query parameter names are converted to underscores automatically. Therefore, you should access these parameters as $_GET["hub_mode"],$_GET["hub_challenge"] and $_GET["hub_verify_token"] if you are writing your callback endpoint in PHP. See this note in the PHP language manual.

Change Notifications

When data changes, and there is a valid subscription, Facebook servers will make an HTTP POST request to the callback_url you specified. The request will have content type of application/json; the body will be a JSON-encoded string containing one or more changes.

Here is one example user object subscription:

{
"object": "user",
"entry": 
[
    {
        "uid": 1335845740,
        "changed_fields": 
        [
            "name",
            "picture"
        ],
       "time": 232323
    },
    {
        "uid": 1234,
        "changed_fields": 
        [
            "friends"
        ],
       "time": 232325
    }
]
}

Note that this does not include the actual data values; to obtain those, you can request them as normal, subject to the usual privacy restrictions. For data that you have access to any time, you may wish to query for that data immediately so that requesting it does not slow down load times when the user returns to your application.

Facebook aggregates changes and sends batched updates every 5 seconds or when number of unsent changes exceeds 1000, so your server(s) should be set up to handle this level of load.

If a change notification to your server fails, Facebook will retry again immediately, then a few times more, with decreasing frequency, over the next 24 hours.

With every response, Facebook sends the X-Hub-Signature HTTP header which contains the SHA1 signature over the response payload, using the application secret as the key - for example: 'X-Hub-Signature: sha1=12345...'. The consumer can verify the signature to validate the integrity of the payload.

Other Examples

Here's what the data returned from an errors subscription might look like:

{
"i":1234,
"o":"errors",
"u":4,
"f":["canvas"],
"d":{
    "url":"http:\/\/www.example.com",
    "suf":"onethefarm\/",
    "e":"HTTPErrorException",
    "c":"500"
    }
 }

Sample Implementations

You can find sample codes at this github location.