Instagram Webhooks

The Webhooks product can send you real-time notifications of changes to select pieces of data. By subscribing your app to the Instagram Webhooks topic, you can receive real-time updates whenever users comment on any of your media objects, mention your business on other user's media objects, or when your stories expire.

To enable Instagram Webhooks:

  1. Set up an endpoint on your server (or use one of our sample apps).
  2. Configure the Webhooks product in your app's App Dashboard.
  3. Associate your app with the Page that's connected to your Business Account.

Please note that user and page update notifications will only be sent if the user/page has installed your app and has not disabled the app platform in their App Settings.

Setting Up an Endpoint

Follow the steps below to set up an endpoint. Alternatively, you can use one of our sample apps and repurpose it for your needs.

If your server is behind a firewall, you may need to whitelist Facebook server IPs to ensure we can send updates to your endpoint.

Verification Requests

When you add or modify the Webhooks product in your app's App Dashboard, we'll send a GET request to your endpoint. You must verify and respond to this request.

Verification requests include the following parameters, appended to the end of your callback URL. Note that PHP converts periods (.) to underscores (_) in parameter names.

  • hub.mode=subscribe
  • hub.challenge — A random string. You will have to pass this back to us.
  • hub.verify_token — A string that you will set when you configure the Webhooks product in your app's App Dashboard.

When your endpoint receives a verification request, it must:

  • Verify that the hub.verify_token value matches the string you set when you configured the Webhooks product.
  • Respond with the hub.challenge value.

Update Notifications

Whenever there's a change to a topic field that you are subsribed to, we'll send your endpoint an update notification. Notifications are of the application/json content type and the body will contain a JSON payload.

JSON Payload

The JSON payload will contain the following properties:

Name Description Type

object

Indicates the object's type.

enum{user, page, permissions, payments}

entry

The list of changes. Multiple changes from different objects that are of the same type are batched together.

object[]

entry.id

The object's ID.

string

entry.changed_fields

An array of the fields that have been updated.

string[]

entry.changes

An array containing the newly updated values.

object[]

entry.time

When the update was sent (not when the change that triggered the updated occurred).

timestamp

The contents and structure of the payload varies depending on the topic and field. Therefore, when setting up or modifying a subscription, we recommend that you test each field by using the Webhooks product Test buttons in your app's App Dashboard.

If you Edit Subscription to Include Values, changes will be returned instead of changed_fields.

Payload Signature

All update notifications include an X-Hub-Signature header containing a SHA1 signature of the request payload, prefixed with sha1=. The signature will be generated using your app's secret as the key, so you can use the signature to validate the payload.

Please note that the signature generation is made using an escaped unicode version of the payload, with lower case hex digits. If you just calculate against the decoded bytes, you will end up with a different signature. For example, the string äöå should be escaped to \u00e4\u00f6\u00e5.

Frequency

Update 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 24 hours. Your server should handle deduplication in these cases. Updates unaccepted for 24 hours will be dropped.

Response

Your endpoint should return a 200 OK HTTPS response for all update notifications.

Configuring the Webhooks Product

Once your endpoint or sample app is ready, use the App Dashboard to add the Webhooks product and Instagram topic to your app.

  1. In the App Dashboard, go to Products > Webhooks, select Instagram from the drop-down menu, then click Subscribe to this topic.
  2. Enter your endpoint's URL in the Callback URL field and enter a string in the Verify Token field. We will include the string in all endpoint verification requests. If you are using one of our sample apps, this should be the same string you used for your app's TOKEN config variable.

Once you click Verify and Save, we'll send your endpoint a verification request which you must validate. Upon successful validation, the last step is to subscribe to individual fields:

  • comment — notifies you when a user comments on a media object you own.
  • mentions — notifies you when a user @mentions your business in a comment or caption that you do not own.
  • story_insights — notifies you when a story you own expires.

Refer to the Instagram Webhooks topic reference to see what information will be included in update notifications.

Associating Your App & Page

You must associate your app to the Page that is connected to your Business Account. To do this, send a POST request to the page's Subscribed Apps edge.

Sample Request

POST graph.facebook.com
  /134895793791914/subscribed_apps

Sample Response

{
  "success": true
}

Sample Apps

We have several sample apps on GitHub which you can set up and repurpose, or which you can use to quickly test your Webhooks configuration.

Let's walk through setting up a sample app on Heroku:

  1. Create a free Heroku account if you don't already have one, then sign into it.
  2. While signed in, go to GitHub and deploy the app to Heroku. The app name you choose will be a part of your endpoint URL, so choose something you can remember. Deploying will take a few seconds.
  3. In a new browser tab, go to your app's App Dashboard and copy your app's App Secret.
  4. Return to Heroku to manage your app. Locate your app's settings and set up two config vars: APP_SECRET and TOKEN. Assign (paste) your app's secret to the APP_SECRET config var, and assign any string to TOKEN. 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).

Your app should be ready to go. You can now return to your app's dashboard and configure the Webhooks product, but before you do that:

  • View your Heroku app. You should see an empty object ([]). This page will display newly received update notification data, so reload it throughout testing.
  • Append /instagram to the end of your Heroku app's URL. This is your endpoint's callback URL, which you'll need during product configuration.
  • Copy the TOKEN value you just set; you'll also need this during product configuration.

What's in the Heroku sample app? I'm glad you asked. The app uses Node.js and these packages:

  • body-parser (for parsing JSON)
  • express (for routes)
  • express-x-hub (for SHA1 support)

Whitelisting Facebook Server IPs

If your server is behind a firewall, you may need to whitelist Facebook server IPs to ensure we can send updates to your callback URLs.

Run this command to get a current list of Facebook server IP addresses:

whois -h whois.radb.net -- '-i origin AS32934' | grep ^route  

It will return a list of IP addresses:

# For example only - over 100 in total
31.13.24.0/21 
66.220.144.0/20    
2401:db00::/32  
2620:0:1c00::/40  
2a03:2880::/32