Webhook Versioning

New Feature

On March 4th, 2020 we introduced Messenger webhook versioning with v6.0 having the first versioned change for the messages field.

The Messenger Platform allows versioning on the events that it sends to apps. Allowing developers to have a window to opt in into the change, once they are ready. For a reference of versioned changes impacting webhooks see the Messenger Platform Changelog.

To have a consistent experience. It's recommended to use the same webhook version for all Messenger Platform fields and API calls.

Changing Versions

Version selectors for each field can be found in the App Dashboard and click on your app. Under Products, Messenger > Settings and the section Webhook Field Version Controls. Changes to these selectors are process live and can be switched back if needed.

Version Availability

Apps can switch live the version for each webhook fields. This allows easy migrations that can be rolled back if they are issues.

The versions available to an app depend on the creation time of the app and the lifetime of the version. The Messenger Platform follows Graph API Versions, for reference on the version lifetime, see available Graph API Versions

Once a version is deprecated all apps still using that version are auto upgraded to the next available version. To avoid auto migrations, make sure to move to the latest version before the selected version is deprecated. Also stay tune to platform announcements specially for breaking changes, the name we give to changes affecting versions before its deprecation timeline.

Webhook events sent to your callback URL have an HTTP header Facebook-API-Version with the string name of the version. This header indicates the version used to build the payload of the webhook event. This header should be used to confirm the field version selection and route the parsing of the event for your app.

Each webhook event correspond to a particular webhook field and the version will correspond to the version selected for that fields. It is possible, though not recommended, to select different versions for each field. For example, if the app is subscribed for messages with v6.0 and to message_echoes with v5.0. Then messages sent from users to a Page will arrive in v6.0, while responses from the Page will be sent as v5.0 events.

Example of webhook event with its HTTP header indicating the version

HTTP Header: Facebook-API-Version: v6.0
    "object": "page",
    "entry": [
            "id": "<PAGE_ID>",
            "time": 1582330662620,
            "messaging": [
                    "sender": {
                        "id": "<PSID>"
                    "recipient": {
                        "id": "<PAGE_ID>"
                    "timestamp": 1582330662412,
                    "message": {
                        "mid": "m_2O976du_...",
                        "text": "Hi"

Migration Flow For Production Apps

Here are the recommended steps. To avoid missing any messages during a migration on a production app. Do the following steps:

  1. Understanding the change. Use test apps to try the new target version and make sure to test the new version changes on the staging environment.

  2. Add logic to the production app to handle both the current and new version. To switch in code, use the value of the Facebook-API-Version HTTP header.

  3. Switch the version on the App Dashboard for all Messenger platform fields to the new target version. On high volume app there might be a few seconds where event in the current version are sent while event in the new version are also getting sent. The app should be able to handle both using the header to switch. Note that events won't be duplicated unless they fail to be delivered.

  4. Monitor your metrics to make sure everything is working as expected, at this stage you can roll back the version change if something does not look right.

  5. Once the migration has been successfully done. Remove the version switch for the now, old version.