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

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.

Ready? Let's get started!