Skip to content
Skills Library
Programming · Analysis

debug-webhooks

/debug-webhooks

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.

Licence
MIT
Last repository change
27.10.2026

Assessment and security

90/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

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.

Original author 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.

How it works

  1. Prerequisites — MCP connection (read first)
  2. Workflow
  3. Common Issues Reference
Original SKILL.md headings · 84 lines, 664 words
SKILL.md preview
---
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
metadata:
  mcp:
    devtools:
      type: streamable-http
      url: "https://mcp.facebook.com/devtools"
---

# 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 |

Versions

The database has no other skills named debug-webhooks.

Database snapshot: 13.11.2026 · package version bc185c21c8a6 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90webhook-setup
    Set up webhooks for a Meta app end-to-end — discover available topics, subscribe to fields, and verify with a test payload. Use when configuring webhooks for the first time or adding new subscriptions.
  • 100pleo-webhooks
    Receive and verify Pleo webhooks. Use when setting up Pleo webhook subscriptions with the Subscriptions API, fetching the whsec_ subscription secret, debugging Standard Webhooks / Svix signature verification (webhook-id, webhook-timestamp, webhook-signature), or handling Pleo…
  • 100opnform-webhooks
    Receive and verify OpnForm webhooks. Use when setting up OpnForm webhook integration handlers, debugging X-Webhook-Signature (sha256=<hex>) HMAC verification, or handling OpnForm form submission payloads.
  • 100webhook-collector
    Create webhook endpoints, send test payloads, and inspect captured events using webhookcollector.dev. Use for both temporary testing and permanent webhook infrastructure. Endpoints are persistent — only event data expires after 24hrs, so pair with a cron to drain events for…
  • 90backend-webhooks
    Use this skill when the user says 'webhook', 'webhook receiver', 'webhook delivery', 'signature verification', 'HMAC', 'event delivery', 'outgoing webhook', 'incoming webhook', 'retry webhook', 'webhook endpoint'. This skill implements receiving, verifying, retrying, and…
  • 100inspect
    Free webhook test URLs from Hookdeck Inspect, with no account or login. Creates a URL with one HTTP call, waits for webhooks to arrive, and reads their headers and exact bodies as JSON. Use when asked to get a webhook test URL, see what a webhook sent, wait or watch for a…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.