# debug-webhooks

Inspects a Meta app's webhook subscriptions, sends test payloads and reports why events are not reaching the callback URL.

Skill by Meta. Category: Testing.

## Install

Project (for this project only):

```sh
npx skills add facebook/agentic-tools --skill debug-webhooks
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

Global (for every project on this machine):

```sh
npx skills add facebook/agentic-tools --skill debug-webhooks -g
```

Works with: Claude Code, Codex CLI, Cursor, Antigravity, Copilot CLI, opencode.

## Tags

- Runs on your computer: It runs as a program on your machine, with your access.

## Security audits

- Gen Agent Trust Hub: Pass
- Socket: Pass
- Snyk: Pass

Installs: 16. Installs counted by skills.sh. [Open on skills.sh](https://www.skills.sh/facebook/agentic-tools/debug-webhooks)

## Source

[Open the source](https://github.com/facebook/agentic-tools/tree/HEAD/plugins/devtools/skills/debug-webhooks). Checked 2026-10-10. This summary may contain AI-generated text, so it can be wrong. Check the source before you rely on it.

## SKILL.md

````markdown
---
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 |
````

- Previous: [api-health](https://syn4pse.dev/terminal/meta-api-health.md)
- Next: [compliance-check](https://syn4pse.dev/terminal/meta-compliance-check.md)
- [Terminal](https://syn4pse.dev/terminal.md)
- [Suggest a change](mailto:terminal@syn4pse.dev?subject=Terminal%20suggestion)
