This document shows you how to create an endpoint on your server to receive webhook notifications from Meta and subscribe to webhook fields for an Instagram professional account using your app. This allows you to receive real-time notifications whenever someone comments on the Media objects of the Instagram professional account using your app, @mentions your app users, when your app users' Stories expire, or when a Instagram user sends a message to that Instagram professional account.
The steps required to receive webhook notifications are as follows:
We provide a sample app on GitHub that deploys on Heroku which you can set up and repurpose, or which you can use to quickly test your Webhooks configuration.
You need the following:
A Verify token which is a string. In your Heroku app's settings, set up two config vars: APP_SECRET
and TOKEN
. Set APP_SECRET
to your app's App Secret and TOKEN
to your password. We will include this string in any verification requests when you configure the Webhooks product in the App Dashboard (the app will validate the request on its own).
View your Heroku app in a web browser. You should see an empty array ([]
). This page will display newly received update notification data, so reload it throughout testing.
/facebook
added to the end. You will need this Callback URL during product configuration.TOKEN
value you set above; you'll also need this during product configuration.The app uses Node.js and these packages:
body-parser
(for parsing JSON)express
(for routes)express-x-hub
(for SHA1 support)You can easily verify that your sample app can receive Webhook events.
curl https://<your-subdomain>.herokuapp.com
in a terminal window.You will need:
Component | Business Login for Instagram | Facebook Login for Business | Instagram Messaging via Messenger Platform |
---|---|---|---|
Access level | Advanced Access | Advanced Access for | Advanced Access |
Access tokens | Instagram User access token | Facebook User or Page access token | Facebook User or Page access token |
Business Verification | Required | Required | Required |
Base URL |
|
|
|
Endpoints |
|
|
|
IDs | The ID of your app user's Instagram professional account | The ID of the Facebook Page linked to your app user's Instagram professional account | The ID of the Facebook Page linked to your app user's Instagram professional account |
Basic Permission | instagram_business_basic | instagram_basic | instagram_basic |
Field Specific Permissions | Refer the Instagram fields table | Refer the Instagram fields table | Refer the Instagram fields table |
comments
and live_comments
webhook notifications.
This step must be completed before you can subscribe to any webhook fields in the App Dashboard.
Your endpoint must be able to process two types of HTTPS requests: Verification Requests and Event Notifications. Since both requests use HTTPs, your server must have a valid TLS or SSL certificate correctly configured and installed. Self-signed certificates are not supported.
The sections below explain what will be in each type of request and how to respond to them. Alternatively, you can use our sample app which is already configured to process these requests.
Anytime you configure the Webhooks product in your App Dashboard, we'll send a GET
request to your endpoint URL. Verification requests include the following query string parameters, appended to the end of your endpoint URL. They will look something like this:
GET https://www.your-clever-domain-name.com/webhooks? hub.mode=subscribe& hub.challenge=1158201444& hub.verify_token=meatyhamhock
Parameter | Sample Value | Description |
---|---|---|
|
| This value will always be set to |
|
| An |
|
| A string that that we grab from the Verify Token field in your app's App Dashboard. You will set this string when you complete the Webhooks configuration settings steps. |
Note: PHP converts periods (.) to underscores (_) in parameter names.
Whenever your endpoint receives a verification request, it must:
hub.verify_token
value matches the string you set in the Verify Token field when you configure the Webhooks product in your App Dashboard (you haven't set up this token string yet).hub.challenge
value.If you are in your App Dashboard and configuring your Webhooks product (and thus, triggering a Verification Request), the dashboard will indicate if your endpoint validated the request correctly. If you are using the Graph API's /app/subscriptions endpoint to configure the Webhooks product, the API will indicate success or failure with a response.
When you configure your Webhooks product, you will subscribe to specific fields
on an object
type (e.g., the photos
field on the user
object). Whenever there's a change to one of these fields, we will send your endpoint a POST
request with a JSON payload describing the change.
For example, if you subscribed to the user
object's photos
field and one of your app's Users posted a Photo, we would send you a POST
request that would look something like this:
POST / HTTPS/1.1 Host: your-clever-domain-name.com/webhooks Content-Type: application/json X-Hub-Signature-256: sha256={super-long-SHA256-signature} Content-Length: 311 { "entry": [ { "time": 1520383571, "changes": [ { "field": "photos", "value": { "verb": "update", "object_id": "10211885744794461" } } ], "id": "10210299214172187", "uid": "10210299214172187" } ], "object": "user" }
Payloads will contain an object describing the change. When you configure the webhooks product, you can indicate if payloads should only contain the names of changed fields, or if payloads should include the new values as well.
We format all payloads with JSON, so you can parse the payload using common JSON parsing methods or packages.
We do not store any Webhook event notification data that we send you, so be sure to capture and store any payload content that you want to keep.
Most payloads will contain the following common properties, but the contents and structure of each payload varies depending on the object fields you are subscribed to. Refer to each object's reference document to see which fields will be included.
Property | Description | Type |
---|---|---|
| The object's type (e.g., |
|
| An array containing an object describing the changes. Multiple changes from different objects that are of the same type may be batched together. |
|
| The object's ID |
|
| An array of strings indicating the names of the fields that have been changed. Only included if you disable the Include Values setting when configuring the Webhooks product in your app's App Dashboard. |
|
| An array containing an object describing the changed fields and their new values. Only included if you enable the Include Values setting when configuring the Webhooks product in your app's App Dashboard. |
|
| A UNIX timestamp indicating when the Event Notification was sent (not when the change that triggered the notification occurred). |
|
We sign all Event Notification payloads with a SHA256 signature and include the signature in the request's X-Hub-Signature-256
header, preceded with sha256=
. You don't have to validate the payload, but you should.
To validate the payload:
X-Hub-Signature-256
header (everything after sha256=
). If the signatures match, the payload is genuine.Your endpoint should respond to all Event Notifications with 200 OK HTTPS
.
Event Notifications are aggregated and sent in a batch with a maximum of 1000 updates. However batching cannot be guaranteed so be sure to adjust your servers to handle each Webhook individually.
If any update sent to your server fails, we will retry immediately, then try a few more times with decreasing frequency over the next 36 hours. Your server should handle deduplication in these cases. Unacknowledged responses will be dropped after 36 hours.
Note: The frequency with which Messenger event notifications are sent is different. Please refer to the Messenger Platform Webhooks documentation for more information.
Your app must enable subscriptions by sending a POST
request to the /me/subscribed_apps
endpoint with the subscribed_fields
parameter set to a comma-separated list of webhooks fields.
Formatted for readability.
POST /me/subscribed_apps ?subscribed_fields=<LIST_OF_WEBHOOK_FIELDS> &<ACCESS_TOKEN>
Value Placeholder | Value Description |
---|---|
| Represents your app user's Instagram professional account ID or the Facebook Page ID that is linked to your app user's Instagram professional account |
| App user's Instagram User access token or Facebook Page access token. |
| A comma-separated list of webhook fields that your app is subscribed to. |
Formatted for readability.
curl -i -X POST \
"https://graph.instagram.com/v22.0
/1755847768034402/subscribed_apps
?subscribed_fields=comments,messages
&access_token=EAAFB..."
On success, your app receives a JSON response with success
set to true
.
{ "success": true }
You can subscribe to the following fields to receive notifications for events that take place on Instagram.
Instagram Webhook field | Instagram API setup with Instagram Login permissions | Instagram API setup with Facebook Login permissions | Instagram Messaging API (Messenger Platform) permissions |
---|---|---|---|
|
|
| x |
|
|
| x |
| Included in the |
| x |
|
| x | Included in the |
|
| x |
|
|
| x |
|
|
| x |
|
|
| x | x |
| x | x |
|
|
| x |
|
|
| x |
|
|
| x |
|
| x | x |
|
|
| x |
|
| x |
| x |
Mutual TLS (mTLS) is a method for mutual authentication. mTLS ensures that the parties at each end of a network connection are who they claim to be by verifying that they both have the correct private key. The information within their respective TLS certificates provides additional verification.
You can Attach a client certificate to Webhooks requests in the App Dashboard when configuring your webhooks.
You must verify the callback URL before enabling mTLS. If you have more than one app, you will need to enable mTLS for each application. Learn more about mTLS in our Webhooks documentation.
Learn how to send and receive messages from Instagram professional accounts