Webhooks for Pages

Subscribe to receive updates to Pages with Webhooks (formerly Real-Time API). When a change occurs, the API sends an HTTP 'POST' request to a callback URL you set up for your app notifying you of a change. You don't need to constantly poll a page for changes such as new posts or Page reviews; the Webhooks can tell your app when a Page's information changes and when you need to make changes to a Page. Your app can get updates for any Page related change in Graph API including messages sent to a page and reading page posts. This is useful if you have SLAs which require you to report when someone contacts a Page.

Set Up a Callback URL

First you'll need to prepare the page that will act as your callback URL. This URL must be accessible by Facebook servers, can receive POST data sent when an update happens, and can receive GET requests in order to verify subscriptions.

For instructions see the Setting Up your Callback URL Guide.

Subscribe to Updates

Add or update your subscription at the /{app-id}/subscriptions Graph API edge. Operations include:

  • Add or modify a subscription
  • List each of your existing subscriptions
  • Delete subscriptions

Note that subscriptions to some updates may require that you get your app whitelisted. For the full Page reference, see the Graph API Reference for the Page node.

Subscribe to Page Posts

Your app can subscribe to a Page's conversations and get notified anytime someone sends a message to a Page:

use Facebook\FacebookSession;
use Facebook\FacebookRequest;

$session = new FacebookSession('<APP_ACCESS_TOKEN>');
$request = new FacebookRequest(
    'object' => 'page',
    'callback_url' => '<YOUR_CALLBACK_URL>',
    'fields' => 'conversations',
    'verify_token' => '<YOUR_VERIFY_TOKEN>',
$response = $request->execute();
curl \
-F "object=page" \
-F "callback_url=<YOUR_CALLBACK_URL>" \
-F "fields=conversations" \
-F "verify_token=<YOUR_VERIFY_TOKEN>" \
-F "access_token=<APP_ACCESS_TOKEN>" \

The parameters used in the call:

Name Description Type


The URL that will receive the POST request when an update is triggered.



An arbitrary string that can be used to confirm to your server that the request is valid.



This is an app access token.


After a Page receives a new post, your callback URL gets a response similar to the following:

Array (
  [object] => page
  [entry] => Array (
    [0] => Array (
      [uid] => 626011956865
      [id] => 626011956865
      [time] => 1418284857
      [changes] => Array (
        [0] => Array (
          [field] => conversations
          [value] => Array (
            [page_id] => 518157959452399,
            [conversation_id] => 93054285730295240750,

Available Updates

The following subscriptions and actions are available for Page. Note that these actions are subject to change.

Promotable Posts

  • promotable_posts - Subscribe and filter updates by type.
  • promotable posts - Subscribe to promotable_posts updates created using object_story_spec with the is_inline parameter.

Page Posts

Supported Actions and Subscription Updates:

  • New Comment on a Post in feed
  • New Like/Unlike on a Post in feed
  • New Like/Unlike on a Comment
  • New Reply on a Comment in feed
  • New Like/Unlike on a Reply
  • Deleted Post in feed
  • Deleted Comment on a Post
  • Deleted Reply on a Comment
  • Edited existing Post in feed
  • Edited existing Comment on a Post
  • Edited existing Reply on a Comment

Not available for Page Posts RTU:

  • New Share on a Post in feed

Page Conversations

For the conversations endpoint of Page object:

  • New Message in Page Inbox from a User
  • New Message in Page Inbox from a Page Admin

Not available for Page conversations RTU:

  • Conversation deleted from Page Inbox
  • Message deleted from Page Inbox