fix(scrapfly-webhooks): handle binary screenshot bodies and correct extraction payload path

[leggetter]

Summary

Closes #65. Fixes two real bugs in scrapfly-webhooks caught while capturing live Scrapfly deliveries for the webhook-samples repo:

1. Screenshot handler crashed on binary bodies. Dispatch reordered to happen before JSON parsing; screenshot path now treats the body as raw image bytes (it is — Scrapfly sends JPEG/PNG/WebP/GIF with a lying Content-Type: application/json).
2. Extraction field path was wrong. payload.result.data → payload.data. The example used to silently log undefined.

What changed

Handler dispatch reordered (Express, Next.js, FastAPI + SKILL.md inline):

+ // Dispatch BEFORE JSON parse — screenshot deliveries are raw image bytes
+ if (resourceType === 'screenshot') {
+   console.log(`Screenshot received: ${req.body.length} bytes (binary)`);
+   return res.status(200).send('OK');
+ }
+
  const payload = JSON.parse(req.body.toString());
  switch (resourceType) {
    case 'scrape':       /* result.url / result.status_code (unchanged) */
-   case 'extraction':   console.log(payload.result?.data);
+   case 'extraction':   console.log({ content_type: payload.content_type, data: payload.data });
-   case 'screenshot':   console.log(payload.result?.screenshot_url);
+   // (no longer reached — handled above)
  }

Next.js framework fix: body reader switched from await request.text() to Buffer.from(await request.arrayBuffer()) — request.text() UTF-8-decodes the bytes and corrupts binary screenshot bodies; arrayBuffer() preserves them so the HMAC verifies correctly.

SKILL.md additions:

• New Prerequisites section flagging the paid-plan requirement (was only in references/setup.md; pulled forward for visibility — FREE-tier accounts hide the webhook UI entirely and have a queue size of 0).
• New "Screenshot is binary, not JSON" bullet in the key facts list, explaining the upstream Content-Type quirk.
• New "Hookdeck Event Gateway alternative" bullet pointing to the built-in SCRAPFLY source type for edge verification.

references/verification.md additions:

• "Screenshot deliveries are binary, not JSON" callout in the common gotchas, with the dispatch-before-parse fix.
• "Alternative: Verify at the Gateway with Hookdeck" section covering the SCRAPFLY source-type plus the known May 2026 caveat (the Content-Type / binary-body mismatch causes Hookdeck to reject screenshot deliveries with UNPARSABLE_JSON when the preset is enabled; route screenshots directly until upstream resolves the Content-Type).
• "Parsed JSON breaks signatures" entry updated to mention the Next.js arrayBuffer() fix.

Tests:

• Two new tests per framework: a screenshot delivery with a binary body (12-byte minimal JPEG header) that asserts the handler returns 200 without crashing, and an invalid-signature variant on the binary body that asserts 401.
• Extraction test rewritten to use the real captured shape ({ content_type, data: {...} }) instead of the bogus { result: { data: {...} } }.

Test plan

• cd skills/scrapfly-webhooks/examples/express && npm test — 24 passed, 0 failed
• cd skills/scrapfly-webhooks/examples/nextjs && npm test — 17 passed, 0 failed
• cd skills/scrapfly-webhooks/examples/fastapi && pytest test_webhook.py -v — 19 passed, 0 failed
• Real-world smoke-test against a live Scrapfly screenshot delivery (out of scope for the PR; relies on a paid Scrapfly account)

Not addressed in this PR

From issue #65, point 3.c (npx install path verification): we already use npx hookdeck-cli listen as the canonical pattern repo-wide (per AGENTS.md, set in PR #40 + #54) and have verified it works against the published hookdeck-cli npm package. Leaving as-is.

Unverified strengths preserved

The signature verification code (JS + Python), the full header list, timing-safe comparison, raw-body capture with express.raw({ type: '*/*' }) / request.arrayBuffer() / await request.body(), the no-replay-window note, and routing by X-Scrapfly-Webhook-Resource-Type all remain unchanged — they matched live behaviour and weren't part of the bug report.

https://claude.ai/code/session_01NNTgQRJss1V7gyzzJ9rjnB

---

Generated by Claude Code