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.

Setup

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

Field Description

message

Subscribes to Message Received events

message_deliveries

Subscribes to Message Delivered events

message_reads

Subscribes to Message Read events

message_echoes

Subscribes to Message Echo events

messaging_postbacks

Subscribes to Postback Received events

messaging_optins

Subscribes to Plugin Opt-in events

messaging_referrals

Subscribes to Referral events

messaging_checkout_updates (BETA)

Subscribes to Checkout Update events

messaging_payments (BETA)

Subscribes to Payment events

messaging_account_linking

Subscribes to Account Linking 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.

{
  "object":"page",
  "entry":[
    {
      "id":"PAGE_ID",
      "time":1458692752478,
      "messaging":[
        {
          "sender":{
            "id":"USER_ID"
          },
          "recipient":{
            "id":"PAGE_ID"
          },

          ...
        }
      ]
    }
  ]
}

Payload

Field Name Description Type

object

Value will be page

String

entry

Array containing event data

Array of entry

entry object

Field Name Description Type

id

Page ID of page

String

time

Time of update (epoch time in milliseconds)

Number

messaging

Array containing objects related to messaging

Array of messaging

messaging object

Field Name Description Type

sender.id

Sender user ID

String

recipient.id

Recipient user ID

String

...

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.

Response

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.

It is extremely important to return a 200 OK HTTP as fast as possible. Facebook will wait for a 200 before sending you the next message. In high volume bots, a delay in returning a 200 can cause significant delays in Facebook delivering messages to your webhook.

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.

Unsubscribe

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.

Batching

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

We may batch events in a single callback, especially during moments of high load. Be sure to iterate over entry and messaging in the response to capture all the events sent in the request.

Security

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. If you just calculate against the decoded bytes, you will end up with a different signature. For example, the string äöå should be escaped to \u00e4\u00f6\u00e5.

Validation

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" \
"https://graph.facebook.com/v2.6/APP_ID/subscriptions_sample"

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.