Stop Polling, Start Pushing: The Case for Webhooks

Today, API users set up “polling” to frequently request updates to ensure they have the most current data. While common, this process is inefficient and chips away at rate limits.

Enter webhooks. Introduced to the industry nearly 20 years ago, webhooks enable one application to provide real-time information to another application via “pushing” data immediately once an event occurs (vs polling). This automatic push means you still get the updated information without a hit to your rate limit.

Think of it this way: instead of walking out to your mailbox every hour to check for new mail (poll), imagine the delivery company sent you a text the minute something was dropped off (push). That text is your webhook.

While webhooks are not new to Meta (or the industry at large), we increasingly hear about API challenges that can be solved via webhook. By pushing updates the instant they occur, they replace inefficient polling with a foundation for automation, speed, and richer integrations. With these benefits in mind, we are excited to showcase our existing webhooks and announce more available immediately.

What webhooks does Meta offer?

Meta offers five standalone webhooks (outlined below) as well as one unified ads subscription endpoint that – with a single setup flow – enables over 88 notifications related to ad object changes and insights updates.

1. Standalone webhooks

Two API calls are required to enable the standalone webhook, using two different access tokens

1. Call <app_id>/subscriptions endpoint using your APP_TOKEN

curl -F "object=ad_account" \
     -F "callback_url=<YOUR_HTTPS_CALLBACK_URL>" \
     -F "fields=effective_status,creative_fatigue" \
     -F "verify_token=<VERIFY_TOKEN>" \
     -F "access_token=<APP_ACCESS_TOKEN>" \
     "https://graph.facebook.com/<APP_ID>/subscriptions"

2. Call act_<ad_account_id>/subscribed_apps using an ACCESS_TOKEN of an Ad Account Admin (can be system user or user token)

curl -F "access_token=<AD_ACCOUNT_ADMIN_SYSTEM_USER_TOKEN>" \
"https://graph.facebook.com/act_<AD_ACCOUNT_ID>/subscribed_apps"

The initial call activates the webhook for your application, instructing our system to prepare all relevant updates for delivery. However, these will remain undelivered until specific ad accounts are identified and access is verified. The subsequent call unblocks the actual delivery for the ad accounts you manage. By providing an Ad Account Admin's ACCESS_TOKEN, you authenticate your permissions and maintain precise control over specific ad accounts.

2. Ads subscription endpoint

The ads subscription endpoint provides real time updates on multiple ad object metrics and insights metrics.

First subscribe to subscriptions field on the ad_account topic:

curl -F "object=ad_account" \
  -F "callback_url=<YOUR_HTTPS_CALLBACK_URL>" \
  -F "fields=subscriptions" \
  -F "verify_token=<VERIFY_TOKEN>" \
  -F "access_token=<APP_ACCESS_TOKEN>" \
  "https://graph.facebook.com/<APP_ID>/subscriptions"

Then set the trigger thresholds and filters for the insights. This example notifies you whenever a campaign is created with an objective set to OUTCOME_SALES in the specified ad account

curl -i -X POST \
  "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/subscriptions" \
  -H "Authorization: Bearer <ACCESS_TOKEN>" \ # Admin of ad account, system user or user access token
  -H "Content-Type: application/json" \
  -d '{
        "event_type": "OBJECT_CREATED",
        "filters": [
          { "field": "entity_type", "value": "CAMPAIGN", "operator": "EQUAL" },
          { "field": "objective",   "value": "OUTCOME_SALES", "operator": "EQUAL" }
        ]
      }'

Then fetch the subscription

curl -G "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/subscriptions/<SUBSCRIPTION_ID>" \
  -d "access_token=${ACCESS_TOKEN}"

Or all subscriptions

curl -G "https://graph.facebook.com/v25.0/act_<AD_ACCOUNT_ID>/subscriptions" \
  -d "access_token=${ACCESS_TOKEN}"

Future plans

We will continue to build out our API webhooks portfolio based on customer needs and feedback.

Resources

• Webhooks developer documentation