Webhooks

The Graph API Webhooks feature allows apps to receive real-time notifications of changes to selected pieces of data.

Overview

Webhooks allows your to app to receive notifications whenever there are updates to a chosen set of topics and their fields. For example, you could set up a webhook for the User topic and subscribe to its email field and be notified whenever your users update their email addresses. This prevents you from having to rely on continuous or even periodic Graph API requests just to check for updates that may or may not have happened. It also helps you avoid rate limiting.

Webhooks update notifications are sent as POST requests to a callback URL that you supply. Notifications can be lightweight, indicating only that a field has been updated, or can include the newly updated value.

Note that you can also receive update notifications for payments. Please refer to the Webhooks for Payments documentation for more information.

Setting Up Subscriptions

You can use the App Dashboard or the /{app_id}/subscriptions edge to create new subscriptions or modify existing ones. Both methods require:

Once you have have these you can begin the setup process.

App Dashboard

To create a new subscription using the App Dashboard:

  1. Sign into your App Dashboard and select your app.
  2. In the navigation menu, click Add Product.
  3. Find Webhooks in the product list and click Get Started.
  4. Select a subscription topic from the drop-down menu and click Subscribe to this topic. The Webhooks topic reference has a complete list of available topics.
  5. Enter your endpoint's callback URL, create a verification token, and choose if you want update notifications to include the newly updated values. Once you click Verify and Save, we'll send you a verification request which you must verify before you can proceed.
  6. After verifying the request, choose each field you want to subscribe to by clicking its corresponding Subscribe button. Refer to each topic's reference documentation for descriptions of individual fields.

To modify an existing subscription:

  1. Sign into your App Dashboard and select your app.
  2. In the navigation menu, click Webhooks.
  3. Use the drop-down menu to select the topic subscription you want to modify.

From here you can edit the topic subscription's callback URL, verification token, and subscribe or unsubscribe from individual fields.

Subscriptions Edge

You can also use the /{app-id}/subscriptions to create new subscriptions or modify existing ones. To subscribe to a topic and specific fields, send a POST request to the /{app-id}/subscriptions edge and include the object (topic), callback URL, fields, and your verification token in the query.

For example:

POST /v2.8/{app-id}/subscriptions HTTP/1.1
Host: graph.facebook.com

object=user
&callback_url=http%3A%2F%2Fexample.com%2Fcallback%2F
&fields=contact_email%2Chometown
&verify_token=MyVerifyString

This will trigger a verification request, which you must verify before you can begin receiving update notifications.

The /{app-id}/subscriptions reference covers all of the edge's operations in more detail.

Permissions

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.

Users can install apps on their own, but pages must use the /{page-id}/subscribed_apps edge.

Callback URL

You need to set up your callback endpoint before you can set up a subscription. The endpoint must use HTTPS for API version 2.5+ and be able to receive both GET and POST requests. All change notifications will be sent as POST requests and include a JSON payload.

If you need more information about setting up HTTPS for your callback endpoint, check out the Getting Started Guide from Let's Encrypt and the SSL Certificate Installation instructions from Digicert.

Verification Requests

We'll send you a GET request to verify your endpoint during setup, or when you update an existing topic subscription. The request will 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
  • hub.verify_token — The verify_token value that you will specify when you enable the Webhook for your app

When your endpoint receives a verification request, it must:

  • Verify the hub.verify_token matches the value you supplied when enabling the Webhook. This is a security check to authenticate the request and identify the Webhook.
  • Respond with the hub.challenge value. This let's us know that your endpoint is configured correctly and that the response is authentic.

Update Notifications

We'll send an HTTPS POST request to your callback URL every time there are updates to any topic fields you have subscribed to. The request will have 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. This is only returned for page subscriptions.

object[]

entry.time

When the update was sent.

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 Test buttons in the Webhooks section of your App Dashboard
  • Examine the payload in each test notification

SHA1 Signature

All requests 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 integrity and payload and it's origin.

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 of up to 1000 updates.

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.

Sample Clients

A few sample clients are available on GitHub.

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