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.

Development Mode

Apps in development mode will receive these Webhook Events but limited to actions taken by users who have a role on the app.

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.

Webhook Event Description


Subscribes to Message Received events


Subscribes to Account Linking events

messaging_checkout_updates (beta)

Subscribes to Checkout Update events


Subscribes to Message Delivered events


Subscribes to Message Echo events


Subscribes to Instant Game events


Subscribes to Handover Protocol events


Subscribes to Plugin Opt-in events

messaging_payments (beta)

Subscribes to Payment events


Subscribes to Policy Enforcement events


Subscribes to Postback Received events

messaging_pre_checkouts (beta)

Subscribes to Payment Pre-checkout events


Subscribes to Message Read events


Subscribes to Referral events


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.



Required 200 OK Response

When you receive a webhook event, you must always return a 200 OK HTTP response. The Messenger Platform will resend the webhook event every 20 seconds, until a 200 OK response is received. Failing to return a 200 OK 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 1 hour, 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 post request will contain an X-Hub-Signature header with the SHA1 signature of the post payload. The signature is calculated using the keyed-hash message authentication code (HMAC) where the key is the app secret. The signature is then 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 raw 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.

Code Example

$appsecret = 'YOUR APP SECRET';
$raw_post_data = file_get_contents('php://input');
$header_signature = $headers['X-Hub-Signature'];

// Signature matching
$expected_signature = hash_hmac('sha1', $raw_post_data, $appsecret);

$signature = '';
    strlen($header_signature) == 45 &&
    substr($header_signature, 0, 5) == 'sha1='
  ) {
  $signature = substr($header_signature, 5);
if (hash_equals($signature, $expected_signature)) {