Terminal
Terminal/Skill
Inspects a Meta app's webhook subscriptions, sends test payloads and reports why events are not reaching the callback URL.
By Meta
Works with
npx skills add facebook/agentic-tools --skill debug-webhooksDiagnose and fix webhook delivery issues for a Meta app.
Start tracking. Before any other work, call devtools_skill_invocation with action start and skill_name debug-webhooks. Pass skill_name debug-webhooks on every devtools_* tool call in the following steps.
Get context. Ask the user for:
app_id via devtools_app_list (action list); if several apps match or it's ambiguous, show the candidates (name, ID, viewer role) and ask the user to pickInspect current state. Run in parallel:
devtools_webhook_list with action list_subscriptions — all active subscriptionsdevtools_webhook_list with action list_topics — all available topics (for comparison)Diagnose. Check for common issues:
No subscriptions found
/webhook-setup to create oneSubscription exists but no events received
devtools_webhook_test with action test_send for the relevant topic and fieldWrong fields subscribed
devtools_webhook_manage with action update_fields, passing the missing fields via add_fieldsdevtools_webhook_manage with action update_fields, passing unwanted fields via remove_fieldsMultiple subscriptions on same topic
Test delivery. For each relevant subscription:
devtools_webhook_test with action test_sendReport findings:
Active Subscriptions
Issues Found
Test Results
Recommended Actions
Apply fixes if the user agrees:
update_fieldsupdate_fieldsupdate_fields cannot change the callback URL — it has no callback_url parameter and silently ignores one. To change the URL, re-run subscribe for the topic with the new URL and verify token: subscribe is an upsert (create-or-update), so it overwrites the URL in place. You do NOT need to unsubscribe first.End tracking. After completing all preceding steps, call devtools_skill_invocation with action end and skill_name debug-webhooks.
| 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 |