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).

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