On March 4th, 2020 we introduced Messenger webhook versioning with v6.0
having the first versioned change for the messages
field.
On Oct 29, 2019 we introduced new webhook fields that allow apps to get user replies to a message and reactions to messages. See Replies and Reaction webhooks
The Messenger Platform sends events to your webhook to notify you 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 a callback URL for webhook events requires verification that you control or own the domain that hosts your application.
GET
request to the callback URL with the parameters listed below.hub.challenge
sent. The URL should validate that the hub.verify_token
matches with the token that was entered in the app dashboard.Parameter | Description |
---|---|
| Set to |
| The custom verify token that the developer provided |
| Generated by the Messenger Platform. Contains the expected response. |
For sample code on how to verify the callback URL, see Webhook Setup. Also see Validating Webhook Events to verify that callback events come from a trusted source.
Apps in development mode will receive these Webhook Events but limited to actions taken by users who have a role on the app.
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 |
| 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 |
| Subscribes to Policy Enforcement events |
| Subscribes to Postback Received events |
| Subscribes to Message Reaction events |
| Subscribes to Message Read events |
| Subscribes to Referral events |
| Subscribes to Handover Protocol Standby Channel events |
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>"
},
...
}
]
}
]
}
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.
To edit your webhook URL or verify token, do the following:
Note any time you change your webhook details, the Messenger Platform will perform a verification of your webhook.
Your webhook should meet the following minimum performance standards:
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.
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.
<?php $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 = ''; if( strlen($header_signature) == 45 && substr($header_signature, 0, 5) == 'sha1=' ) { $signature = substr($header_signature, 5); } if (hash_equals($signature, $expected_signature)) { echo('SIGNATURE_VERIFIED'); } ?>