Realtime Updates

Introduction

The Graph API supports Realtime Updates to enable your app to subscribe to changes in data. Your app can then cache data and receive updates, rather than continuously polling Facebook’s servers. Caching data and using this API can improve the reliability of your app 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 app will generally receive notification of the change within a couple of minutes of its occurrence.

There are two steps to set up a subscription for Realtime Updates:

1. Set up a public endpoint URL that receives both HTTP GET (for subscription verification) and POST (for actual change data) requests from Facebook. The structure of both of these types of requests is described below.

2. Set up subscriptions for the updates you want to receive for your app. The easiest way to do this is to use the App Dashboard's Realtime Updates panel.

It is also possible to set up and list subscriptions programmatically, through the Graph API. Both the Realtime Updates panel and the subscription API are described in the Managing Realtime Update Subscriptions guide.

---

Types of Updates

It is possible to subscribe to the following types of updates:

• User – Get notifications about certain user fields and connections
• Page - Get notifications when pages that have installed your app as a Tab change some of their public properties
• Permissions – Get notifications when your users change the permissions they grant your app
• Payments – Get notifications relating to Facebook Payments
• Payment Subscriptions – Get notifications relating to Facebook Payment Subscriptions
• Errors – Get notifications relating to errors
• Page - Get notifications about posts, attribute changes and a number of other items. This is available to either apps installed as a visible Tab or an invisible app that has a page_access token. Please see the realtime section of the Pages API reference for more info.

Note that you can not subscribe to changes on all properties and connections of the User object. Connections to which you can subscribe include: feed, friends, activities, interests, music, books, movies, television, likes, checkins, location, events.

Similarly, for Page objects, you can only subscribe to some of the attributes of the page. For the complete list, please see the realtime section of the Page reference.

---

Your Callback Server

Your callback server must handle two types of requests. Ensure it is on a public URL so that Facebook can make these requests successfully.

Subscription Verification

Firstly, Facebook servers will make a single HTTP GET to your callback URL when you try to add or modify a subscription. A query string will be appended 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 specified when you created the subscription

The endpoint should first verify the hub.verify_token. This ensures that your server knows the request is being made by Facebook and relates to the subscription you just configured.

It should then echo just the hub.challenge value back, which confirms to Facebook that this server is configured to accept callbacks, and prevents denial-of-service (DDoS) vulnerabilities.

Note for PHP developers: In PHP, dots and spaces in query parameter names are converted to underscores automatically. Therefore, you should access these parameters using $_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 for more details.

Realtime Updates

Following a successful subscription, Facebook will proceed to call your endpoint every time that there are changes (to the chosen fields or connections). For each update, it will make an HTTP POST request.

The request will have content type of application/json and the body will comprise a JSON-encoded string containing one or more changes.

Note for PHP developers: In PHP, to get the encoded data you would use the following code:

$data = file_get_contents("php://input");
$json = json_decode($data);

Note that the hub.mode, hub.challenge and hub.verify_token parameters are not sent again once the subscription has been confirmed.

Here is one example of a callback made for a user object subscription. In it, two users' field changes are batched together:

{
  "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 (either from before or after the update). To obtain those, your app can request them as normal, subject to the usual privacy restrictions. For data that you have access to at any time, you may wish to query for that data immediately following this callback so that it is ready for when the user returns to your app.

Facebook aggregates changes and sends batched updates every 5 seconds, or when the number of unsent changes exceeds 1,000. Your endpoint should be set up to handle this level of load, although of course, actual traffic depends on the subscriptions you configure.

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

With every request, Facebook sends a X-Hub-Signature HTTP header which contains the SHA1 signature of the request payload, using the app secret as the key, and prefixed with sha1=. Your callback endpoint can verify this signature to validate the integrity and origin of the payload.