facebook Debug Webhooks
Diagnose and fix webhook delivery issues for a Meta app.
Workflow
Start tracking. Before any other work, call
devtools_skill_invocationwith actionstartandskill_namedebug-webhooks. Passskill_namedebug-webhookson everydevtools_*tool call in the following steps.Get context. Ask the user for:
- The app name or ID — if they give a name (or aren't sure of the ID), resolve it to an
app_idviadevtools_app_list(actionlist); if several apps match or it's ambiguous, show the candidates (name, ID, viewer role) and ask the user to pick - What's going wrong (not receiving events? wrong data? specific topic?)
- The app name or ID — if they give a name (or aren't sure of the ID), resolve it to an
Inspect current state. Run in parallel:
devtools_webhook_listwith actionlist_subscriptions— all active subscriptionsdevtools_webhook_listwith actionlist_topics— all available topics (for comparison)
Diagnose. Check for common issues:
No subscriptions found
- The topic the user expects events from has no active subscription
- Suggest using
/webhook-setupto create one
Subscription exists but no events received
- Send a test payload:
devtools_webhook_testwith actiontest_sendfor the relevant topic and field - If test fails: callback URL may be down, unreachable, or not returning 200
- If test succeeds but real events don't arrive: the issue is likely on the app side (permissions, page subscriptions, etc.)
Wrong fields subscribed
- Compare subscribed fields against what the user expects to receive
- If fields are missing: use
devtools_webhook_managewith actionupdate_fields, passing the missing fields viaadd_fields - If extra fields cause noise: use
devtools_webhook_managewith actionupdate_fields, passing unwanted fields viaremove_fields
Multiple subscriptions on same topic
- Flag potential conflicts or duplicate delivery
Test delivery. For each relevant subscription:
- Call
devtools_webhook_testwith actiontest_send - Report whether the test payload was accepted by the callback endpoint
- Call
Report findings:
Report Format
Active Subscriptions
- Topic, fields, callback URL for each
Issues Found
- Each issue with severity (critical / warning / info)
- Root cause analysis
- Suggested fix
Test Results
- Topic/field tested → success or failure
- Response details if available
Recommended Actions
- Ordered list of fixes to apply
Apply fixes if the user agrees:
- Add missing fields via
update_fields - Remove unwanted fields via
update_fields - Callback URL changes:
update_fieldscannot change the callback URL — it has nocallback_urlparameter and silently ignores one. To change the URL, re-runsubscribefor the topic with the new URL and verify token:subscribeis an upsert (create-or-update), so it overwrites the URL in place. You do NOT need tounsubscribefirst.
- Add missing fields via
End tracking. After completing all preceding steps, call
devtools_skill_invocationwith actionendandskill_namedebug-webhooks.
Common Issues Reference
| Symptom | Likely Cause | Fix |
|---|---|---|
| No events received | No subscription exists | Subscribe to the topic |
| No events received | Callback URL returns non-200 | Fix server endpoint |
| No events received | App lacks page/account subscription | Subscribe the page to the app |
| Partial events | Missing fields in subscription | Add fields via update_fields |
| Duplicate events | Multiple subscriptions on same topic | Unsubscribe duplicates |
| Test works, real events don't | Permission or page-level issue | Check app permissions and page subscriptions |
| Need to change callback URL | update_fields has no callback_url param (silently ignored) | Re-run subscribe for the topic with the new URL + verify token — it upserts and overwrites the URL in place; no unsubscribe needed |