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

messages

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

messaging_policy_enforcement

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

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

          ...
        }
      ]
    }
  ]
}

Payload

Property Type Description

object

String

Value will be page

entry

Array of entry

Array containing event data

entry object

Property Type Description

id

String

Page ID of page

time

Number

Time of update (epoch time in milliseconds)

messaging

Array<messaging>

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.id

String

Sender user ID

recipient.id

String

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.

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. 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.

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. 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.