Setup Webhooks Subscriptions

• Step 1. Create an endpoint on your server to receive webhooks from Meta
  • Verify requests from Meta – Occurs in the Meta App Dashboard
  • Accept and validate JSON payloads from Meta – Occurs on your server
• Step 2. Subscribe your app to webhook fields – Occurs in the Meta App Dashboard
• Step 3. Enable your app user’s Instagram professional account to receive notifications via an API call to Meta
• Step 4. Test the setup by sending a message to your Instagram professional account.

• A free Heroku account,
• Your app’s App Secret found on Meta App Dashboard App settings > Basic
• 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.
• Your app’s Callback URL will be your Heroku app’s URL with /facebook added to the end. You will need this Callback URL during product configuration.
• Copy the TOKEN value you set above; you’ll also need this during product configuration.

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

1. Under the Webhooks product in your App Dashboard, click the Test button for any of the Webhook fields.
2. A pop-up dialog will appear showing a sample of what will be sent. Click Send to My Server.
3. You should now see the Webhook information at the Heroku app’s URL, or use curl https://<your-subdomain>.herokuapp.com in a terminal window.

• Your app must be set to Live in the App Dashboard for Meta to send webhook notifications

• Apps must be set to Live in the App Dashboard to receive webhook notifications.
• Advanced Access is required to receive comments and live_comments webhook notifications.
• The Instagram professional account that owns the media objects must be public to receive notifications for comments or @mentions.⁠
• Notifications for Comments on Live media are only sent during the live broadcast.
• Account level webhooks customization is not supported. If your app user is subscribed to any Instagram webhook field, your app receives notifications for all fields the app is subscribed to.
• Album IDs are not included in webhook notifications. Use the Comment ID received in the notification to get the album ID.
• The ad ID will not be returned for media used in dynamic ads.
• Notifications for story_insights events will only show metrics for the first 24 hours, before the story expires, even if the story is a highlight.

GET https://www.your-clever-domain-name.com/webhooks?
  hub.mode=subscribe&
  hub.challenge=1158201444&
  hub.verify_token=meatyhamhock

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"
}

POST /me/subscribed_apps
  ?subscribed_fields=<LIST_OF_WEBHOOK_FIELDS>
  &<ACCESS_TOKEN>

curl -i -X POST \
  "https://graph.instagram.com/v25.0/1755847768034402/subscribed_apps
  ?subscribed_fields=comments,messages
  &access_token=EAAFB..."

{
  "success": true
}

1. Install the Meta outbound API CA certificate
2. Verify the client certificate against the CA certificate
3. Verify the common name (client.webhooks.fbclientcerts.com) of the client certificate

1. Download the Meta outbound API CA certificate (meta-outbound-api-ca-2025-12.pem) to your server, for example to /etc/ssl/certs/meta-outbound-api-ca-2025-12.pem
2. Turn on mTLS by Nginx directives

   ssl_verify_client          on;
   ssl_client_certificate     /etc/ssl/certs/meta-outbound-api-ca-2025-12.pem;
   ssl_verify_depth           3;
   
3. Verify the CN from Nginx embedded variable $ssl_client_s_dn equals "client.webhooks.fbclientcerts.com" (

   if ($ssl_client_s_dn ~ "CN=client.webhooks.fbclientcerts.com") {
        return 200 "$ssl_client_s_dn";
   }
   

1. Download the Meta outbound API CA certificate (meta-outbound-api-ca-2025-12.pem) to an S3 bucket.
2. Configure the HTTPS listener on the ALB to enable mTLS with the trust store containing the Meta CA certificate in the S3 bucket.
3. In your application code, extract the CN from the HTTP header “X-Amzn-Mtls-Clientcert-Subject”⁠, and verify it equals "client.webhooks.fbclientcerts.com".

1. Send your Instagram professional account a test message (the public account added in the Meta App Dashboard for testing). This should trigger a messages webhook event. The notification should contain the recipient.id, set to your Instagram professional account’s Instagram-scoped ID, and the is_echo and is_self properties, both set to true, within the messaging array.
2. Send a response to your Instagram-scoped ID using the API.

• Webhooks from Meta | Developer Documentation