Webhooks for Messenger Platform

Webhooks allows you to receive real-time HTTP notifications of changes to specific objects in the Meta Social Graph. For example, we could send you a notification when a customer sends your business a message. Webhooks notifications allow you to track messaging changes and avoid rate limits that would occur if you were querying the Messenger Platform endpoints to track changes.

To successfully implement Webhooks for Messenger Platform you will need to:

  1. Create an endpoint on your server to receive and process your Webhooks notifications, a JSON object
  2. Configure the Meta Webhooks product in your App Dashboard
  3. Subscribe to the Meta Webhooks notifications you want to receive
  4. Install your app on your Facebook Page

Before You Start

Before you start we assume you have:

Create an Endpoint

Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.

The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.

Verification Requests

Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:

Sample Verification Request

GET https://www.your-clever-domain-name.com/webhooks?
  hub.mode=subscribe&
  hub.challenge=1158201444&
  hub.verify_token=meatyhamhock
ParameterSample ValueDescription

hub.mode

subscribe

This value will always be set to subscribe.

hub.challenge

1158201444

An int you must pass back to us.

hub.verify_token

meatyhamhock

A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps.

Note: PHP converts periods (.) to underscores (_) in parameter names .

Vadating Verification Requests

Whenever your endpoint receives a verification request, it must:

  • Verify that the hub.verify_token value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).
  • Respond with the hub.challenge value.

If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.

Event Notifications

When you configure your Webhooks product, you will subscribe to specific fields on an object type (for example, the messages field on the page object). Whenever there's a change to one of these fields, we will send your endpoint a POST request with a JSON payload describing the change.

For example, if you subscribed to the page object's message_reactions field and a customer reacted to a message your app sent, we would send you a POST request that would look something like this:

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

          ...
        }
      ]
    }
  ]
}

Payload Contents

Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.

We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.

We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.

Validate Payloads

We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's 'X-Hub-Signature-256' header, preceded with 'sha256='. You don't have to validate the payload, but you should and we strongly recommend that you do.

To validate the payload:

  1. Generate a SHA256 signature using the payload and your app's App Secret.
  2. Compare your signature to the signature in the X-Hub-Signature-256 header (everything after sha256=). If the signatures match, the payload is genuine.

Please note that we generate the signature using an escaped unicode version of the payload, with lowercase 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.

Respond to Event Notifications

Your endpoint should respond to all notifications:

  • with a 200 OK HTTPS response
  • within 5 or less seconds

Webhooks Delivery Retry

If delivery of a notification fails for more than 15 minutes, an alert is sent to your App Dashboard.

If delivery of a notification continues to fail for 1 hour, you will receive a Webhooks Disabled alert, and your app will be unsubscribed from the webhook for the Page. Once you have fixed the issues you will need to subscribe to the Webhooks again.

Configuring the Webhooks Product

Once your endpoint or sample app is ready, use your app's App Dashboard to add and configure the Webhooks product. You can also do this programmatically by using the /{app-id}/subscriptions endpoint.

In this example we'll use the dashboard to configure a Webhook and subscribe to the messages field. Any time a customer sends your app a message, a notification will be sent to your Webhooks endpoint.

  1. In the App Dashboard, go to Products > Webhooks, select Page from the drop-down menu, then click Subscribe to this object.
  2. Enter your endpoint's URL in the Callback URL field and add your verification token to the Verify Token field. We will include this string in all Verification Requests. If you are using one of our sample apps, this should be the same string you used for your app's TOKEN config variable.

    If you want event notification payloads to include the names of the fields that have changed as well as their new values, set the Include Values toggle to Yes.
    Entering an endpoint URL and a verification token string.
  3. Once you click Verify and Save, we'll send your endpoint a Verification Request which you must validate.

  4. The last step is to subscribe to individual fields. Subscribe to the messages field and send a test Event Notification.

    If your endpoint is set up correctly, it should validate the payload and execute whatever code you have set it up to do upon successful validation. If you are using our sample app, load the app's URL in your web browser. It should display the payload's contents.

You can change your Webhooks subscriptions, verify token, or version at any time using the App Dashboard.

Available Messenger Platform Fields

Webhooks Field Description

message_deliveries

A notification is sent when a message that was sent by a Page has been delivered to a customer.

message_echoes

A notification is sent when a Page has sent a message

messages

A notification is sent when your Page has received a message from a customer.

messaging_account_linking

A notification is sent when a customer links or unlinks their Messenger account from their account with your business.

messaging_game_plays

A notification is sent when a person has played a round of an Instant Game.

messaging_handovers

A notification is sent when a change has occurred during the Handover Protocol

messaging_optins

A notification is sent when a customer has clicked a Messenger plugin, accepted a message request using customer matching, or has opted in to receive messages via the checkbox plugin.

messaging_policy_enforcement

A notification is sent when a policy enforcement warning has been sent or a policy enforcement action has been taken on the app associated with the Page.

messaging_postbacks

A notification is sent when a customer clicks a postback button, Get Started button, or persistent menu item.

message_reactions

A notification is sent when a customer reacts to a message sent by the Page.

message_reads

A notification is sent when a customer reads a message sent by the Page.

messaging_referrals

A notification is sent when a customer resumes a conversation with the Page by clicking an m.me link, an ad, or chat plugin.

standby

A notification is sent when a conversation is idle for an app during the Handover Protocol

Connect Your App

You will need to connect your Webhooks app to your Page and subscribe your Page to the Webhooks notifications you want to receive.

Add the App

You can connect an app to a Page in the Meta Business Suite > Business Assets .

Subscribe your Page

You will need to subscribe your Page to the Webhooks notifications you want to receive.

Requirements

To subscribe to a Webhooks field, send a POST request to the Page's subscribed_apps edge using the Page's acccess token.

curl -i -X POST "https://graph.facebook.com/PAGE-ID/subscribed_apps
  ?subscribed_fields=messages
  &access_token=PAGE-ACCESS-TOKEN"
  

Sample Response

{
  "success": "true"
}

To see which app's your Page has installed, send a GET request instead:

Sample Request

curl -i -X GET "https://graph.facebook.com/PAGE-ID/subscribed_apps
  &access_token=PAGE-ACCESS-TOKEN"

Sample Response

{
  "data": [
    {
      "category": "Business",
      "link": "https://my-clever-domain-name.com/app",
      "name": "My Sample App",
      "id": "APP-ID"
      "subscribed_fields": [
        "messages"
      ]
    }
  ]
}

If your Page has not installed any apps, the API will return an empty data set.

Graph API Explorer

You can also use the Graph API Explorer to send the request to subscribe your Page to a Webhooks field.

  1. Select your app in the Application dropdown menu.
  2. Click the Get Token dropdown and select Get User Access Token, then choose the pages_manage_metadata permission. This will exchange your app token for a User access token with the pages_manage_metadata permission granted.
  3. Click Get Token again and select your Page. This will exchange your User access token for a Page access token.
  4. Change the operation method by clicking the GET dropdown menu and selecting POST.
  5. Replace the default me?fields=id,name query with the Page's id followed by /subscribed_apps, then submit the query.

Learn More