Instagram Webhook Mentions Not Working: Complete Fix Guide

Based on your description, the issue is likely related to Instagram’s webhook limitations for mentions in development mode or configuration problems. When you mention your business account from a personal account, Instagram’s webhook system requires proper setup that differs from direct message notifications that are working correctly.

Contents

• Common Causes of Instagram Mention Webhook Issues
• Step-by-Step Troubleshooting Guide
• Configuration Requirements for Mention Notifications
• Testing and Verification Methods
• Alternative Solutions

Common Causes of Instagram Mention Webhook Issues

The most frequent reasons why Instagram mention webhooks don’t work include:

App Review Status: Instagram Graph API webhooks for mentions only work in development mode for users with specific roles in your app. According to Stack Overflow discussions, you need to get your app reviewed and put into live mode before mentions will trigger webhooks for general users.

Missing Permissions: Your access token must include the instagram_business_basic and instagram_business_manage_comments permissions to receive mention notifications. Without these, your webhook won’t have access to mention events.

Improper Webhook Subscription: Many developers forget to explicitly subscribe to the “mentions” webhook topic. The Instagram Platform documentation states that you need to subscribe to mentions, comments, and other relevant topics separately.

Business Account Connection: Your Instagram business account must be properly connected to a Facebook Page in the Meta dashboard. If this connection isn’t established, mention events won’t be captured.

Step-by-Step Troubleshooting Guide

1. Verify App Review Status

Check if your app is in development or live mode:

• Navigate to your app in the Meta Developer Dashboard
• Ensure your app has been submitted for review and approved
• If in development mode, mentions will only work for users with roles in your app (Admin, Developer, or Tester)

Important: As noted in developer discussions, “in dev mode this will only work for actions taken by users that have a role in the app. You will need to get your app reviewed and put it into live mode, before it will work for anyone else.”

2. Check Permissions

Verify your access token has the correct permissions:

// Required permissions for mention webhooks
const requiredPermissions = [
  'instagram_basic',
  'instagram_business_basic',
  'instagram_business_manage_comments'
];

3. Validate Webhook Subscription

Ensure you’re subscribed to the mentions topic:

• Go to Webhooks in your Meta App Dashboard
• Verify you’re subscribed to “mentions” specifically
• Test the subscription with the official Meta testing tools

4. Confirm Business Account Setup

Check that your business account is properly linked:

• Your Instagram business account @veris_this must be connected to a Facebook Page
• The Facebook Page must be properly integrated with your Meta app
• Verify the account has business status (not personal)

Configuration Requirements for Mention Notifications

Webhook Endpoint Configuration

Your webhook endpoint must be properly configured to handle Instagram mention events:

1. HTTPS Requirement: Your endpoint must use HTTPS
2. Verification: Complete the webhook verification process
3. Event Handling: Implement proper handling for mention events

Minimal Webhook Handler Example

app.post('/webhook', (req, res) => {
  // Verify the webhook signature first
  if (!verifyWebhookSignature(req)) {
    return res.status(403).send('Invalid signature');
  }

  const { object, entry } = req.body;
  
  if (object === 'instagram') {
    entry.forEach(change => {
      change.messaging.forEach(messagingEvent => {
        if (messagingEvent.mention) {
          // Handle mention event
          console.log('Received mention:', messagingEvent);
        }
      });
    });
  }

  res.status(200).send('EVENT_RECEIVED');
});

Subscription Process

To subscribe to mention notifications, follow these steps:

1. Create Webhook: In Meta Dashboard → Webhooks → Create Webhook
2. Enter Callback URL: Your HTTPS endpoint URL
3. Select Fields: Choose “mentions” field
4. Verify Subscription: Complete the verification challenge
5. Test: Use the test button in the dashboard

Testing and Verification Methods

Testing in Development Mode

When testing in development mode, you have limited options:

Method 1: Use an account with Admin, Developer, or Tester role to create mentions
Method 2: Use the “Test Webhook” feature in the Meta Dashboard for comment events (though this may not work for mentions)

Verification Checklist

Use this checklist to verify your setup:

• [ ] App is in Live mode (not Development)
• [ ] Access token has required permissions
• [ ] Webhook is subscribed to “mentions” topic
• [ ] Business account is connected to Facebook Page
• [ ] Endpoint is HTTPS and properly verified
• [ ] Handling code can process mention events

Alternative Solutions

1. Polling Approach

If webhooks continue to be problematic, consider polling the Instagram API:

// Poll for mentions every 5 minutes
async function checkForMentions() {
  const mentions = await instagramAPI.get('/mentions', {
    access_token: accessToken,
    fields: 'id,username,timestamp,text'
  });
  
  if (mentions.data.length > 0) {
    // Process new mentions
    processMentions(mentions.data);
  }
}

setInterval(checkForMentions, 300000); // 5 minutes

2. Use Page Mentions Instead

If you’re having trouble with Instagram-specific mentions, consider monitoring Facebook Page mentions instead, which often have more reliable webhook support.

3. Contact Instagram Support

If you’ve tried all the above solutions and still have issues, contact Instagram Business Support through the Meta Business Suite.

Sources

1. Instagram Graph API Webhook Documentation
2. Instagram Webhook Not Triggering - Stack Overflow
3. Why Instagram Graph API Webhook Not Working - Stack Overflow
4. Reddit Discussion on Instagram API Webhook Issues
5. Instagram Platform Documentation

Conclusion

Instagram mention webhook notifications can be challenging to configure correctly. Based on your situation where DMs work but mentions don’t, the most likely causes are either your app being in development mode (limiting mentions to specific users) or missing proper webhook subscription to the mentions topic. Start by checking your app review status and webhook configuration, then verify all required permissions and business account connections. If the issue persists, consider implementing a polling approach as a temporary solution while you work with Instagram support to resolve the webhook configuration issues.