Instagram Mentions API: Why Your @Mention Webhooks Never Arrive
comments field is subscribed - and when someone @mentions your client in a caption or a comment on a post the client does not own, Instagram sends nothing. Mentions are not one feature behind one switch. They sit behind four independent gates, and three of them live outside your codebase entirely. This is why social-listening, UGC and reputation tools stall for weeks on what looks like a webhook bug.What the Mentions API actually gives you
Meta's Instagram Platform documentation describes mentions as identifying captions, comments and media in which a Business or Creator alias has been tagged or @mentioned. On the Instagram Login configuration there are exactly two endpoints: GET /<IG_ID>/tags to retrieve the media a professional account has been tagged in, and POST /<IG_ID>/mentions to reply to a comment or caption the account was @mentioned in. On the Facebook Login configuration the read side is the mentioned_media edge instead.
Nothing here is a stream of mentions. The webhook tells you that an event happened; the API tells you what it was. Both halves are granted separately, and the permission names are not the same on the two login paths.
The four layers a mention has to pass through
1. Permission
Instagram Login needs instagram_business_basic and instagram_business_manage_comments. Facebook Login needs instagram_basic, instagram_manage_comments, pages_manage_metadata, pages_read_engagement and pages_show_list - five scopes for one feature.
2. Access level
Standard Access only covers accounts that have a role on your app. Serving clients you do not own or manage requires Advanced Access, and Meta documents Advanced Access as required for comments and live_comments notifications specifically.
3. App mode and subscription
Your app must be set to Live before Meta sends any notification, and each professional account has to be enabled separately through POST /me/subscribed_apps. Registering a callback URL in the App Dashboard subscribes nobody.
4. Account privacy
Meta states that webhooks are not sent if the media the comment or @mention appears on was created by an account set to private, and that the account owning the media must be public to receive comment or @mention notifications at all.
Layer 4 is the one that ends most debugging sessions badly: the integration is correct, the mention genuinely happened, and the notification was never sent by design. No error, no log line, nothing to fix in code.
The payload is deliberately thin
Meta's webhooks reference for the mentions field returns two values and nothing else: media_id and comment_id. No caption, no username, no comment text. Every mention notification is therefore a two-step operation - receive the event, then call back into the API with that ID to find out what was actually said, using a token that already carries the right scope. If the scope is missing, the callback fails silently long after the webhook appeared to succeed.
There is a second trap in the subscription model. Account-level customisation is not supported: if an app user is subscribed to any Instagram webhook field, your app receives notifications for every field the app is subscribed to. You cannot subscribe a client to mentions alone, so your handler has to correctly ignore a stream of traffic it never asked for.
Where the two login paths quietly diverge
- On Instagram Login, mentions are not a separately subscribable field - Meta documents them as included in the
commentswebhook notification - On Facebook Login,
mentionsis its own field with its own five-permission requirement and its own review path - Mentions on Stories are not supported by the Mentions API, so a large share of real-world brand mentions is simply out of scope
- Commenting on photos you were tagged in is not supported, so a product that promises a reply to every mention does not survive contact with the API
- The two paths use different hosts and different token types, so a mentions feature built for one does not port to the other - settle this before you build, using Instagram Login vs Facebook Login
Why mention features fail App Review
None of these are product problems. They are evidence problems - the submission does not prove, in the format reviewers work in, that the mention path functions for an account the applicant does not control. That is fixable on resubmission, but every cycle costs weeks.
What a working mentions integration actually needs
The correct login configuration, chosen first
The permission names, the host and the review scope all change with it, and switching later is a rebuild rather than a setting.
Advanced Access on the comment-capable scopes
Which means Business Verification and per-permission App Review before a single real client can connect. Start with Instagram API Advanced Access approval.
A subscription step inside your onboarding flow
Every account has to be enabled individually after OAuth completes. Most teams discover this only after the first paying client reports silence.
A submission built around the mention path itself
Reviewers reject what they cannot reproduce, and a mention flow is one of the harder ones to stage convincingly. The scope it depends on is covered in the instagram_manage_comments approval guide.
The exact permission set, the reviewer-facing test path and the screencast script that demonstrates a mention arriving are where these submissions are won or lost. That preparation work is deliberately not written out here.
Facts in this article are based on Meta's official Instagram Platform documentation - the Mentions guide, the Webhooks setup guide and the Instagram webhooks reference - reviewed August 2026. Meta makes all App Review, permission and enforcement decisions independently; outcomes and timelines cannot be guaranteed. Not affiliated with or endorsed by Meta Platforms, Inc.