Webhook

The Messenger Platform sends events to your webhook to notify your bot when a variety of interactions or events happen, including when a person sends a message. Webhook events are sent by the Messenger Platform as POST requests to your webhook.

Setting Up Your Webhook

For complete steps on setting up your webhook, see Webhook Setup.

Webhook Events

The available webhook events are listed below. All webhook events are optional, so select those that are most relevant for the experience you are trying to create.

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

messaging_account_linking

Subscribes to Account Linking events

messaging_checkout_updates (beta)

Subscribes to Checkout Update events

message_deliveries

Subscribes to Message Delivered events

message_echoes

Subscribes to Message Echo events

messaging_handovers (beta)

Subscribes to Handover Protocol events

messaging_optins

Subscribes to Plugin Opt-in events

messaging_payments (beta)

Subscribes to Payment events

messaging_policy_enforcement

Subscribes to Policy Enforcement events

messaging_postbacks

Subscribes to Postback Received events

messaging_pre_checkouts (beta)

Subscribes to Payment Pre-checkout events

message_reads

Subscribes to Message Read events

messaging_referrals

Subscribes to Referral events

standby (beta)

Subscribes to Handover Protocol Standby Channel events

Event Format

All webhook events 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. In addition to the properties shown below, each event also has its own event-specific properties.

Note that entry is an array and may contain multiple objects, so ensure your code iterates over it to process all events. For a complete description of event properties, see Webhooks Reference.

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

          ...
        }
      ]
    }
  ]
}

Required 200 OK Response

When you receive a webhook event, 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.

Changing Your Webhook

To edit your webhook URL or verify token, do the following:

  1. In your app dashboard, click the "Add Product" button.
  2. Add the "Webhooks" product. That will present you with an interface to edit your webhook.
  3. In the Webhooks settings, click the 'Edit Subscriptions' button.
  4. Update your webhook details.
  5. Click the 'Verify and Save' button. The Messenger Platform will verify your webhook and save the new details on success.

Note any time you change your webhook details, the Messenger Platform will perform a verification of your webhook.

Webhook Performance Requirements

Your webhook should meet the following minimum performance standards:

  • Respond to all webhook events with a 200 OK.
  • Respond to all webhook events in 20 seconds or less.

If your webhook fails to meet either of the above requirements for more than 15 minutes a 'Webhooks Failing' alert will appear in the 'Alerts' page of your app settings.

If your webhook continues to fail for 8 hours, you will receive a 'Webhooks Disabled' alert, and your Facebook app will be unsubscribed from receiving webhook events for the Page.

Once you have fixed the issues with your webhook, you must set up your webhook again.

Validating Webhook Events

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.