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"
}

Permissions

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

Webhooks inherit from these same permissions. This means that even if you set up a webhook and subscribe to specific fields on an object type, your webhook won't notify you of any changes to an object of that type unless:

  • your app has been reviewed and approved for the permission which 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)

Applications will only be able to receive test webhooks sent from the app dashboard while they are in development mode. No production data, including that of app admins, developers, and testers, will be delivered unless the app is live.

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!