Webhooks

Webhooks allows you to receive real-time HTTP notifications of changes to specific objects in the Facebook Social Graph. For example, we could send you a notification when any of your app Users change their email address or whenever they comment on your Facebook Page. This prevents you from having to query the Graph API for changes to objects that may or may not have happened, and helps you avoid reaching your rate limit.

Webhooks for Payments and Webhooks for Messenger have slightly differently configuration steps. If you are setting up a Webhook for either of these products, please refer to their respective documents for setup instructions.

Objects, Fields, and Values

There are many types of objects in the Facebook Social Graph, such as User objects and Page objects, so whenever you configure a Webhook you must first choose an object type. Since different objects have different fields, you must then subscribe to specific fields for that object type. Whenever there's a change to the value of any object field you have subscribed to, we'll send you a notification.

Notifications are sent to you as HTTP POST requests and contain a JSON payload that describes the change. For example, let's say you set up a User Webhook and subscribed to the Photos field. If one of your app's Users uploads a photo, we'd send you a notification that would look like this:

Sample Notification

{
  "entry": [
    {
      "time": 1520383571,
      "changes": [
        {
          "field": "photos",
          "value": {
            "verb": "update",
            "object_id": "10211885744794461"
          }
        }
      ],
      "id": "10210299214172187",
      "uid": "10210299214172187"
    }
  ],
  "object": "user"
}

App Review

Before an app can be made public, it typically must go through App Review. During review, apps can request approval for specific login permissions, which control the types of data the app can access when using the Graph API.

Although the Webhooks product does not require App Review, it does respect these same login permissions. This means that even if you set up a Webhook and subscribe to specific fields on an object type, you won't receive notifications of any changes to an object of that type unless:

  • your app has been approved for the login permission that corresponds to that type of data, and
  • the object that owns the data has granted your app permission to access that data (e.g., a User allowing your app to access their feed)

Although apps in development mode are automatically approved for all login permissions, they will not receive live Webhooks notifications unless the person who installed the app has an Admin, Developer, or Tester role on the app.

Setup

To use Webhooks, you will need to set up an endpoint on your server, then add and configure the Webhooks product in your app's dashboard. The rest of these documents explain how to complete both of these steps.

Ready? Let's get started!