[garethx]

Requested by Gareth · project thread

Adds instagram-webhooks and messenger-webhooks, matching the new INSTAGRAM and MESSENGER source types in hookdeck/core#6195. Each has SKILL.md, references (overview, setup, verification), and Express, Next.js and FastAPI examples with tests, plus providers/instagram.yaml and providers/messenger.yaml with testScenario and catalog.summary. README.md and marketplace.json are left to the post-merge Sync Catalog workflow.

What each skill covers

• instagram-webhooks (object: "instagram"): the three API setups (Unified Login, Instagram Login, Facebook Login), with the fields and permissions matrix for each and /subscribed_apps per setup. Entries carry changes[] (comments, live_comments, mentions, story_insights) or messaging[] (message including is_echo/is_deleted/handoff admin_text, reaction, postback, referral, read for messaging_seen, message_edit), plus standby[].
• messenger-webhooks (object: "page"): entry[].messaging[] and standby[]. The handler maps each item's event key to its field (messages, message_echoes, messaging_postbacks, message_reads, message_deliveries, message_reactions, messaging_optins, messaging_referrals, message_edits, messaging_account_linking). It also covers the 5-second response window and the 1-hour "Webhooks Disabled" unsubscribe.

Verification (same as core's HMAC alias): X-Hub-Signature-256: sha256=<hex>, HMAC-SHA256 of the raw body keyed with the app secret, hex. Node checks /^sha256=([0-9a-f]{64})$/i before Buffer.from(..., 'hex'), then runs crypto.timingSafeEqual on equal-length buffers. Python uses hmac.compare_digest on bytes. Express reads the body with express.raw({ type: '*/*' }), and Next.js reads arrayBuffer(). There's no timestamp window. The GET handshake uses INSTAGRAM_VERIFY_TOKEN / MESSENGER_VERIFY_TOKEN, and each setup section says Hookdeck's edge answers it. Tests cover Meta's escaped-unicode signing: a body with \u00e4\u00f6\u00e5 verifies over its raw bytes, and a signature over the re-serialized (decoded) JSON is rejected. Each skill's Setup section and references/setup.md repeat core's configuration_alert word for word.

Results

• ./scripts/validate-provider.sh passes for both skills.
• ./scripts/test-examples.sh instagram-webhooks messenger-webhooks: 6/6 example runs pass (Instagram 41/33/38 tests, Messenger 35/29/33).
• sync --validate passes.
• test-agent-scenario.sh <provider> express --dry-run runs for both.

Worth a look

• Which secret signs Instagram webhooks: Meta's setup guide only says "your app's App Secret", and its sample app copies it from App settings > Basic. The docs don't say whether Instagram Login apps sign with the Instagram app secret. The skill says so and follows core's alert: try the App Secret first, then the Instagram app secret.
• Meta's docs disagree with each other in places, and the skills handle both versions:
  • Comment payloads use value.id (Instagram Login) or value.comment_id (Unified/Facebook Login).
  • Some examples-page samples are wrapped in a JSON array, so the Instagram handlers accept both forms.
  • The examples page's story_insights sample is a copy of the postback sample, so its fields come from the Graph API Instagram webhooks reference instead.
  • The Messenger messaging_postbacks reference shows a {field, value} sample with sender.user_ref.
• README.md and .claude-plugin/marketplace.json are not edited here. The Sync Catalog workflow regenerates them after merge, as CONTRIBUTING describes.
• Hookdeck answers the hub.challenge handshake itself without checking the Verify Token, so any value entered in the Meta dashboard works. Each skill's Setup section and references/setup.md say so.

Docs: Instagram webhooks setup, fields, examples, Messenger Platform webhooks, webhook events.

https://claude.ai/code/session_01Mp6z12EgZRFuEhuPqFwxMT

---

Generated by Claude Code