Webhook Reference

Below are the callbacks that are delivered to your webhook for the Messenger Platform.

If you need to learn how to setup a webhook, read the detailed docs. This will walk you through the general setup, the format of the data and how to verify the call came from Facebook.

Webhook Events

When you setup your webhook, there are 11 relevant webhook events (subscription fields) for this integration. All fields are optional so select the fields most relevant for your experience.

Webhook Event Description


Subscribes to Message Received events


Subscribes to Message Delivered events


Subscribes to Message Read events


Subscribes to Message Echo events


Subscribes to Postback Received events


Subscribes to Plugin Opt-in events


Subscribes to Referral events

messaging_checkout_updates (BETA)

Subscribes to Checkout Update events

messaging_payments (BETA)

Subscribes to Payment events


Subscribes to Account Linking events


Subscribes to Policy Enforcement events

Payment-related callbacks are in beta and will only appear to developers who have access. Request access to our beta program for payments.

Edit your Webhook

In order to edit your webhook, click the "Add Product" button in the App Dashboard and add the "Webhook" option. That will present you with an interface to edit your webhook.

Subscribe App to Page

Subscribe an app to get updates for a page. You can do this in the Webhooks section under the Messenger Tab.

A page may have up to 10 apps subscribing to it.

Or you can do this via API:

curl -X POST "https://graph.facebook.com/v2.6/me/subscribed_apps?access_token=PAGE_ACCESS_TOKEN"    

If successful, you will receive a response:

  "success": true

Note that to create a subscription, the owner of the page access token must have moderator admin access or higher on the Page.

Common Format

All callbacks for the Messenger Platform have a common structure.




Field Name Description Type


Value will be page



Array containing event data

Array of entry

entry object

Field Name Description Type


Page ID of page



Time of update (epoch time in milliseconds)



Array containing objects related to messaging

Array of messaging

messaging object

Field Name Description Type


Sender user ID



Recipient user ID



Additional callback specific fields

When representing a user, these IDs are page-scoped IDs (PSID). This means that the IDs of users are unique for a given page.

If you have an existing Facebook Login integration, user IDs are app-scoped and will not work with the Messenger platform.


Your webhook callback should always return a 200 OK HTTP response when invoked by Facebook. Failing to do so may cause your webhook to be unsubscribed by the Messenger Platform.

A delivery receipt will automatically be sent to the user after your webhook has acknowledged the message. You can also use Sender Actions to notify that the message has been seen.


If your webhook returns an error (i.e., not a 2XX status) or times out (i.e., takes longer than 20 second to respond) for over 15 minutes, then we will send you a warning developer alert.

If your webhook continues to fail for 8 hours, then we will send you a developer alert that the webhook is being disabled and we will unsubscribe your app. Once you've fixed your issues, you must re-add your webhook and re-subscribe your app to the page.


Note that entry is an array and may contain multiple objects. Be sure to iterate over entry to process all events. Although messaging is also an array, there is no batching mechanism for messaging at the moment. Each messaging object contains a sender and recipient. The object will also contain a data depending on the type of callback.


The HTTP request will contain an X-Hub-Signature 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

Please note that the calculation is made on the escaped unicode version of the payload, with lower case hex digits. For example, the string äöå will be escaped to \u00e4\u00f6\u00e5. The calculation also escapes / to \/, < to \u003C, % to \u0025 and @ to \u0040. If you just calculate against the decoded bytes, you will end up with a different signature.


You can test if your webhook works correctly and you're subscribed to a page using the following endpoint:

curl \
-F "object_id=PAGE_ID" \
-F "object=page" \
-F "field=messages" \
-F 'custom_fields={"page_id": PAGE_ID}' \
-F "access_token=PAGE_ACCESS_TOKEN" \

As a result within a few seconds you should receive a webhook event with the following data:

[ { field: 'messages', value: { page_id: PAGE_ID } } ]

This can be helpful, if you want to make sure that your subscription is alive and your webhook is receiving updates.