messaging_postbacks Webhooks Reference

This document explains the JSON payload your webhooks server will receive when a messaging postback webhook event is triggered. A postback webhook event is triggered when a person clicks a postback button, Get Started button, or persistent menu item.

Example Notification

The following is an example of the JSON payload that will be sent to your webhooks server.

  "field": "messaging_postbacks",
  "value": {
    "sender": {
      "user_ref": "USER-REF-ID"
    "recipient": {
      "id": "PAGE-ID"
    "timestamp": "1527459824",
    "postback": {
      "mid": "m_MESSAGE-ID",
      "title": "TITLE-FOR-THE-CTA",
      "payload": "USER-DEFINED-PAYLOAD",
      "referral": {
        "source": "SHORT-URL",
        "type": "OPEN_THREAD"

JSON Properties

All JSON properties in a webhook notification are strings.



The ID for the message


Information defined in the CTA payload parameter. This is only included in the webhook notification sent to the app that sent the message to the person.


Information about the action the person took to enter a conversation.

The referral property information is included in the webhook notification only when a person starts a conversation using one of the following then clicking a CTA such as a Get Started button:

  • A Chat Plugin
  • An Link
  • A Click to Messenger Ad
  • A Messenger QR Code
  • A Welcome Screen


The arbitrary data that was originally passed in the ref param added to the link. Only alphanumeric characters as well as -, _, and = are supported


The URL for this referral. For links, the value of source is “SHORTLINK”. For referrals from Messenger Conversation Ads, the value of source is "ADS"


The identifier for the referral. For referrals coming from links, it will always be "OPEN_THREAD".


The title for the Call To Action (CTA) that a person clicked

The ID for your Facebook Page


The ID for the reference for a person who took an action, such as clicked a Get Started, Chat Plugin or Persistent Menu item, that sent a message


The Unix timestamp for date when the webhook notification was sent to your server

See Also

Additional developer documentation to further your understanding of concepts mentioned in this Messaging Postbacks Webhooks guide.