Messenger Platform


Webhook Events

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.

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

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

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

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 that includes information you will need to process and respond to the event, including the PSID of the sender and recipient of the event. Below is the common format shared by all webhook events. In addition to these, each webhook event will also have its own event-specific properties.




Property Type Description



Value will be page


Array of entry

Array containing event data

entry object

Property Type Description



Page ID of page



Time of update (epoch time in milliseconds)



Array of one messaging object. Note that even though this is an array, it will only contain one messaging object.

messaging object

In addition to these, each webhook event will include event-specific properties.

Property Type Description


Sender user ID


Recipient user ID

Responding to a Webhook Event

When you receive a webhook event from the Messenger Platform, you must always return a 200 OK HTTP response. 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.