debug-webhooks

# Debug Webhooks Diagnose and fix webhook delivery issues for a Meta app. ## Prerequisites — MCP connection (read first) This skill needs the Meta Social Technologies MCP server `devtools` (`https://mcp.facebook.com/devtools`, streamable-http). Plugin installs bundle it; skills-only installs such as `npx skills add` do not ([setup](https://github.com/facebook/agentic-tools#install-via-vercel-skillssh)). **If the `mcp__devtools__*` tools are not available, STOP.** Do not invent tool output, including the step 1 tracking call. Ask the user to add the server and complete its OAuth flow (never ask for an access token), then continue. ## Workflow 1. **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. 2. **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_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 pick - What's going wrong (not receiving events? wrong data? specific topic?) 3. **Inspect current state.** Run in parallel: - `devtools_webhook_list` with action `list_subscriptions` — all active subscriptions - `devtools_webhook_list` with action `list_topics` — all available topics (for comparison) 4. **Diagnose.** Check for common issues: **No subscriptions found** - The topic the user expects events from has no active subscription - Suggest using `/webhook-setup` to create one **Subscription exists but no events received** - Send a test payload: `devtools_webhook_test` with action `test_send` for 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_manage` with action `update_fields`, passing the missing fields via `add_fields` - If extra fields cause noise: use `devtools_webhook_manage` with action `update_fields`, passing unwanted fields via `remove_fields` **Multiple subscriptions on same topic** - Flag potential conflicts or duplicate delivery 5. **Test delivery.** For each relevant subscription: - Call `devtools_webhook_test` with action `test_send` - Report whether the test payload was accepted by the callback endpoint 6. **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 7. **Apply fixes** if the user agrees: - Add missing fields via `update_fields` - Remove unwanted fields via `update_fields` - **Callback URL changes: `update_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.** 8. **End tracking.** After completing all preceding steps, call `devtools_skill_invocation` with action `end` and `skill_name` `debug-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 |