debug-webhooks

Debug Webhooks

Diagnose and fix webhook delivery issues for a Meta app.

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