webhook-setup

Webhook Setup

Interactive wizard to configure webhooks on a Meta app from scratch.

Workflow

1. Start tracking. Before any other work, call devtools_skill_invocation with action start and skill_name webhook-setup. Pass skill_name webhook-setup on every devtools_* tool call in the following steps.

2. Identify the app. Ask the user for the app name or ID. If they give a name (or aren't sure of the ID), call devtools_app_list (action list) and resolve it to an app_id — match the name case-insensitively. If several apps match or it's ambiguous, show the candidates (name, ID, viewer role) and ask the user to pick. If they give a numeric ID, use it directly.

3. Check existing state. Run in parallel:

   • devtools_webhook_list with action list_topics — show all available webhook topics
   • devtools_webhook_list with action list_subscriptions — show what's already subscribed

4. Present the options. Show the user:

   • Available topics (e.g., page, user, instagram, whatsapp_business_account)
   • Which topics already have active subscriptions
   • For each topic, list the subscribable fields

5. Collect subscription details. Ask the user for:

   • Topic — which webhook topic to subscribe to
   • Fields — which fields within that topic (e.g., feed, messages)
   • Callback URL — their HTTPS endpoint (must be live and pass Meta's verification challenge)
   • Verify token — the token their server expects for the verification handshake

6. Subscribe. Call devtools_webhook_manage with action subscribe:

   • Pass topic, fields, callback_url, verify_token
   • If the subscription fails, explain the likely cause:
     • Callback URL not reachable → server must be running and publicly accessible
     • Verification failed → verify token mismatch or endpoint not responding to GET challenge
     • Invalid fields → check field names against the topic's available fields

7. Verify with a test payload. After successful subscription:

   • Call devtools_webhook_test with action test_send for one of the subscribed fields
   • Confirm whether the test payload was delivered
   • If test fails, suggest checking server logs and endpoint configuration

8. Summary. Show the final state:

   • Topic and fields subscribed
   • Callback URL configured
   • Test result (success/failure)

9. End tracking. After completing all preceding steps, call devtools_skill_invocation with action end and skill_name webhook-setup.

Tips

• If the user wants to modify an existing subscription (add/remove fields), use devtools_webhook_manage with action update_fields instead of unsubscribe + resubscribe.
• Always verify after subscribing — a successful subscribe call doesn't guarantee payloads will be delivered correctly.
• Remind users that their callback URL must handle both the GET verification challenge and POST event payloads.