Meta Webhooks — Instagram Graph API Integration

A developer-facing service that mirrors the Curalate / Bazaarvoice UGC collection pattern for Instagram, built on the Instagram Graph API and Meta Webhooks.

---

Features

Feature	Endpoint
Meta webhook verification + events	GET/POST /webhook
Load one @mention (after webhook)	GET /instagram/user/{id}/mentioned_media/{media_id}
Pull posts from photo-tags	GET /instagram/user/{id}/tags
Hashtag search — recent posts	GET /instagram/hashtag/{tag}/recent
Hashtag search — top posts	GET /instagram/hashtag/{tag}/top
Look up any Instagram username	GET /instagram/user/by-username/{username}
Own post feed	GET /instagram/user/{id}/media
Single post detail	GET /instagram/media/{id}
Engagement metrics per post	GET /instagram/media/{id}/insights
List comments on a post	GET /instagram/media/{id}/comments
Filter comments by username	GET /instagram/media/{id}/comments/by-user/{username}
Post a comment	POST /instagram/media/{id}/comments
Reply to a comment	POST /instagram/comments/{id}/reply
Delete a comment	DELETE /instagram/comments/{id}
Sync & store comments locally	POST /comments/sync/{media_id}
Query tracked comments	GET /comments/tracked
Track comments by username	GET /comments/tracked/user/{username}
Webhook event log	GET /webhook/events

---

Quick Start

1. Clone & install

git clone https://github.com/FasterApiWeb/Meta-WebHooks.git
cd Meta-WebHooks
pip install -r requirements.txt

Developers (tests ≥90% coverage, MkDocs):

pip install -r requirements-dev.txt
pytest
mkdocs serve

Full guides: docs/ (built with MkDocs — see Installation, Usage, Tutorial).

2. Configure credentials

cp .env.example .env

Edit .env:

INSTAGRAM_ACCESS_TOKEN=your_long_lived_token
INSTAGRAM_APP_ID=your_app_id
INSTAGRAM_APP_SECRET=your_app_secret
INSTAGRAM_USER_ID=your_instagram_business_user_id
META_WEBHOOK_VERIFY_TOKEN=choose_any_secret_string

3. Run locally

python run.py

Swagger UI → http://localhost:8000/docs ReDoc → http://localhost:8000/redoc

---

Exposing the Webhook to Meta

Meta requires an HTTPS endpoint. Use ngrok or Cloudflare Tunnel to proxy your local server:

ngrok

ngrok http 8000
# Forwarding: https://abc123.ngrok.io -> http://localhost:8000

Cloudflare Tunnel (no account required)

cloudflared tunnel --url http://localhost:8000
# Your quick Tunnel has been created! Visit it at: https://xyz.trycloudflare.com

Register in Meta for Developers

1. Go to developers.facebook.com → Your App → Webhooks
2. Choose Instagram and click Edit Subscription
3. Set:
   • Callback URL: https://<your-tunnel-host>/webhook
   • Verify token: the value of META_WEBHOOK_VERIFY_TOKEN in your .env
4. Subscribe to the fields you need: mentions, comments, story_insights, feed

Meta will GET /webhook?hub.mode=subscribe&hub.challenge=...&hub.verify_token=... and the server will respond with the challenge to complete verification.

---

Required Meta App Permissions

Permission	Used for
instagram_basic	User profile, own media, hashtag search
instagram_manage_comments	Read & write comments, photo-tagged media
instagram_manage_mentions	@mention media
instagram_manage_insights	Engagement metrics (impressions, reach, saves…)
pages_read_engagement	Business Discovery API (lookup by username)

All permissions must be approved in your Meta App Review before going live. For development you can test with your own accounts without App Review.

---

Getting Your Access Token

1. Create a Meta App at developers.facebook.com (type: Business)
2. Add the Instagram Graph API product
3. Connect your Instagram Business / Creator account via your Facebook Page
4. Generate a User Access Token with the permissions above
5. Exchange it for a Long-Lived Token (60-day expiry):

curl "https://graph.facebook.com/oauth/access_token\
?grant_type=fb_exchange_token\
&client_id=APP_ID\
&client_secret=APP_SECRET\
&fb_exchange_token=SHORT_LIVED_TOKEN"

6. Get your Instagram User ID:

curl "https://graph.facebook.com/v19.0/me/accounts\
?fields=instagram_business_account\
&access_token=LONG_LIVED_TOKEN"

---

Project Structure

Meta-WebHooks/
├── app/
│   ├── main.py               # FastAPI app + Swagger config
│   ├── config.py             # Pydantic settings (reads .env)
│   ├── database.py           # SQLite via SQLAlchemy (auto-created)
│   ├── routers/
│   │   ├── webhook.py        # Meta hub verification + event receiver
│   │   ├── instagram.py      # Instagram Graph API proxy endpoints
│   │   └── comments.py       # Local comment tracking / query
│   ├── services/
│   │   └── instagram_api.py  # Async httpx wrapper for Graph API
│   └── models/
│       └── schemas.py        # Pydantic request/response models
├── docs/                     # MkDocs source
├── tests/                    # pytest (90%+ coverage on app/)
├── mkdocs.yml
├── requirements.txt
├── requirements-dev.txt
├── .env.example
└── run.py                    # uvicorn entry point

---

Data Persistence

All data is stored in meta_webhooks.db (SQLite, auto-created on first run):

Table	Contents
webhook_events	Every raw event received via POST /webhook
tracked_comments	Comments synced manually or received via webhook

---

Environment Variables Reference

Variable	Description
INSTAGRAM_ACCESS_TOKEN	Long-lived Instagram User or Page access token
INSTAGRAM_APP_ID	Your Meta App ID
INSTAGRAM_APP_SECRET	Your Meta App Secret
INSTAGRAM_USER_ID	Numeric IG Business/Creator account ID
META_WEBHOOK_VERIFY_TOKEN	Secret string for webhook hub verification
GRAPH_API_VERSION	Graph API version (default: v19.0)
DATABASE_URL	Optional SQLite URL (tests default to pytest_meta.db)
HOST	Bind address (default: 0.0.0.0)
PORT	Port (default: 8000)