debug-webhooks

name	debug-webhooks
description	Troubleshoot webhook issues for a Meta app — inspect active subscriptions, identify misconfiguration, and send test payloads to verify delivery. Use when webhooks aren't working as expected.
allowed-tools	mcp__devtools__devtools_webhook_list, mcp__devtools__devtools_webhook_manage, mcp__devtools__devtools_webhook_test, mcp__devtools__devtools_app_list, mcp__devtools__devtools_skill_invocation
license	MIT

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

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