Skip to content

Subscribed Apps Endpoint(subscribed_apps)

Also called: WABA subscription · Subscribe app to WABA · /{waba-id}/subscribed_apps

The /{WABA_ID}/subscribed_apps endpoint connects a WhatsApp Business Account to your Meta app, so that account's webhooks start flowing to your callback URL.

Reviewed

What is the subscribed_apps endpoint?

The subscribed apps endpoint, /{WABA_ID}/subscribed_apps, is the Graph API edge that connects one WhatsApp Business Account (WABA) to a Meta app. A POST with an access token that can manage the account subscribes the calling app and returns {"success": true}. A GET lists the apps subscribed to the account, each under whatsapp_business_api_data with its id, name and link. A DELETE unsubscribes the app. It belongs to the WhatsApp Business Management API and needs the WhatsApp Business Management permission (whatsapp_business_management).

Webhooks need two switches, and this is the second. The first is the app-level webhook subscription in the App Dashboard: the callback URL, the verify token and the fields you want, such as messages or account_update. That decides where events go and which kinds, but it delivers nothing on its own. Only once a WABA is subscribed to the app through this endpoint do that account's events start arriving. Every WABA has to be subscribed individually.

The same POST can carry a webhook override. Sending override_callback_uri (up to 200 characters) and a verify_token points that WABA's supported webhooks, such as messages, at a different, verified endpoint. A GET then shows override_callback_uri beside the app's details, and re-subscribing with no body removes it. A phone-number-level override, set on the number's webhook_configuration, wins over the WABA's. Template and account-level webhooks always go to the app's default callback URL.

Key takeaways

  • The subscribed_apps endpoint (POST /{WABA_ID}/subscribed_apps) connects one WhatsApp Business Account to your app so its webhooks flow.
  • App-level webhook fields choose what to receive, but nothing arrives until each WABA is subscribed through this endpoint.
  • A GET lists the apps subscribed to a WABA and a DELETE unsubscribes yours — the call to make when a customer offboards.
  • Adding override_callback_uri and verify_token to the POST sends that WABA's supported webhooks to a different endpoint.
  • Re-subscribing with an empty body removes the override, so retry jobs must resend it every time.

See InfiQ pricing

Interactive stop

Press Send to connect a WABA to your app

2 / 2
POSThttps://graph.facebook.com/v26.0/102290129340398/subscribed_apps

POST 200 in 650 ms

Request

2 headers
POST /v26.0/102290129340398/subscribed_apps HTTP/1.1
Host: graph.facebook.com
Authorization: Bearer {ACCESS_TOKEN}

Response

200 OK
HTTP/1.1 200 OK
Content-Type: application/json; charset=UTF-8
{
"success": true
}
Try another response
The subscribe call as it goes over the wire, with Meta's success reply. Toggle the alternatives to see the errors a wrong WABA ID or an expired token produce.

Response: 200 OK after 650 ms.

How does the subscribed_apps endpoint work?

  1. Configure the app's webhook once

    In the App Dashboard set the HTTPS callback URL and verify token, answer Meta's verification GET, and subscribe the app to the fields you need. This applies to every WABA you later connect.

  2. Get the customer's WABA ID

    After Embedded Signup, the account update webhook with event: PARTNER_ADDED carries it in waba_info.waba_id; your signup flow can also return it directly to your front end.

  3. POST to subscribed_apps

    Call POST /{WABA_ID}/subscribed_apps with a token that has whatsapp_business_management access to that account, usually a system user access token. Expect {"success": true}.

  4. Confirm with a GET

    Call GET /{WABA_ID}/subscribed_apps and check your app's id is in data. Send a test message to the number and watch it arrive before telling the customer they are live.

  5. Override or unsubscribe when needed

    Add override_callback_uri and verify_token to route this account's messages elsewhere, re-subscribe with an empty body to remove the override, and DELETE when the customer leaves.

The subscribed_apps endpoint in code

# Subscribe your app to the customer's WABA
curl -X POST "https://graph.facebook.com/v26.0/{WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
# -> {"success": true}
 
# Same call with a WABA-level callback override
curl -X POST "https://graph.facebook.com/v26.0/{WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer {ACCESS_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{"override_callback_uri": "https://hooks.example.com/whatsapp/{WABA_ID}", "verify_token": "{VERIFY_TOKEN}"}'
 
# List subscribed apps
curl "https://graph.facebook.com/v26.0/{WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"
# -> {"data": [{"whatsapp_business_api_data": {"id": "{APP_ID}", "link": "...", "name": "{APP_NAME}"}}]}
 
# Unsubscribe (offboarding)
curl -X DELETE "https://graph.facebook.com/v26.0/{WABA_ID}/subscribed_apps" \
  -H "Authorization: Bearer {ACCESS_TOKEN}"

One call per WABA. Re-subscribing with no body removes any WABA-level override.

Example: Going live for a jewellery chain in Ahmedabad

An Ahmedabad SaaS company onboards a jewellery chain through Embedded Signup. Seconds after the owner finishes, an account_update webhook with PARTNER_ADDED brings the new WABA ID. The backend calls POST /{WABA_ID}/subscribed_apps, gets {"success": true}, confirms its app appears in the GET listing and sends a test message from a staff phone. The test arrives as a messages webhook, and the chain's shared inbox is switched on. In an earlier version the team had skipped the call; templates were approved, but customer replies never appeared.

— Going live for a jewellery chain in Ahmedabad

Common mistakes with the subscribed_apps endpoint

  • Configuring fields but never subscribing

    Ticking messages in the App Dashboard does not connect any account. If webhooks never arrive for a new customer, check the GET listing for that WABA before debugging your endpoint.

  • Using a token without access to the WABA

    A token that cannot manage the account gets error 100 with subcode 33 (object does not exist or missing permissions). Use a system user token assigned to that WABA with whatsapp_business_management.

  • Wiping an override by accident

    Re-subscribing with no body removes the WABA's override. An onboarding retry job that re-posts blindly can silently move a customer's messages back to the default URL. Include the override on every re-post.

  • Expecting the override to catch everything

    Overrides apply to supported fields such as messages. Template status, template quality and account_update events still go to the app's default callback URL, so keep that endpoint working.

The subscribed_apps endpoint: key facts and limits

Subscribe
POST /{WABA_ID}/subscribed_apps
Success response
{"success": true}
List
GET returns data[].whatsapp_business_api_data (id, name, link)
Unsubscribe
DELETE /{WABA_ID}/subscribed_apps
Scope
One WABA per call; repeat for every account
Permission
whatsapp_business_management
WABA override
override_callback_uri (max 200 characters) + verify_token

Why does the subscribed_apps endpoint matter?

"Webhooks are configured but nothing arrives" is one of the most common WhatsApp integration problems, and a missing subscription is usually the cause. For a partner onboarding many businesses, the call is the moment a new customer's account goes live in the platform: until it succeeds, their customers' messages reach Meta but never reach the inbox or the bot. For offboarding, the matching DELETE is how you stop receiving a former customer's data.

subscribed_apps FAQs

Why am I not receiving WhatsApp webhooks after setting the callback URL?+
Usually because the WABA is not subscribed to your app. Setting the callback URL and fields in the App Dashboard is only half the setup: call POST /{WABA_ID}/subscribed_apps for the account, confirm your app in the GET listing, then send a test message to the number.
Do I need subscribed_apps if I only use my own WABA?+
Yes. Every WABA whose webhooks you want must be subscribed to your app. For a single account it is usually a one-time call, which a provider may make on your behalf; a GET on the edge shows whether it has been done.
Can more than one app receive webhooks for the same WABA?+
The GET response is a list with one entry per subscribed app, so an account can be connected to more than one app, for example when several partners serve one business.
How do I stop a WABA override?+
Call POST /{WABA_ID}/subscribed_apps again with no body. The override is removed and the account's webhooks return to the app's default callback URL.

Best practices for the subscribed_apps endpoint

  • Make the subscribe call idempotent and safe to retry: posting again simply re-confirms the subscription.
  • Run a nightly job that GETs subscribed_apps for every active WABA and alerts on any that lost your app.
  • DELETE the subscription and revoke stored tokens as part of every offboarding.
  • Log the WABA ID, app ID and time of each subscribe call; support will ask for them.

Talk to InfiQ

From definition to your first message

InfiQ is an official Meta Business Partner. Start a 7-day free trial — no card needed — and see this running on your own number.

Start free trialBrowse all 550 terms