firecrawl-webhooks-events — Claude Code skill: what it does
firecrawl-webhooks-events sets up Firecrawl webhook ingestion with raw HMAC-SHA256 signature verification, deduplication, and polling fallback.
MIT 1 installs ★ 2,935 updated 2026-10-29
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a claude-codeWhat firecrawl-webhooks-events does
This skill guides the agent to treat incoming Firecrawl webhooks as authenticated hints for a state machine rather than standalone triggers. It enforces timing-safe HMAC-SHA256 validation against raw payload bytes before running JSON parsers or triggering side effects. A missing secret is never treated as valid.
Endpoints must acknowledge delivery with a 2xx response within 10 seconds, as Firecrawl retries dropped deliveries only at 1, 5, and 15 minutes before terminating. The skill explicitly guards against waiting on non-existent crawl.failed or batch_scrape.failed events, requiring reconciliation through provider polling APIs instead.
What it helps with
- Verify raw HMAC-SHA256 signatures before parsing incoming webhooks
- Deduplicate crawl, batch, extract, and monitor event deliveries
- Reconcile missing terminal crawl events by polling status APIs
Example prompts for the agent
- Implement a Firecrawl webhook receiver with raw body signature checks in
src/webhooks/firecrawl.ts - Add deduplication and durable inbox storage for Firecrawl events
- Set up job status polling for terminal crawl and batch outcomes
How to install firecrawl-webhooks-events
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a claude-code2Manually: put the files in place
~/.claude/skills/firecrawl-webhooks-events/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/firecrawl-webhooks-events/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a codex2Manually: put the files in place
.agents/skills/firecrawl-webhooks-events/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a cursor2Manually: put the files in place
.cursor/skills/firecrawl-webhooks-events/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install jeremylongshore/tons-of-skills-marketplace skills/.curated/firecrawl-webhooks-events2Manually: put the files in place
.github/skills/firecrawl-webhooks-events/SKILL.md1Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a gemini-cli2Platform CLI
gemini skills install https://github.com/jeremylongshore/tons-of-skills-marketplace --path skills/.curated/firecrawl-webhooks-eventsManually: put the files in place
.devin/skills/firecrawl-webhooks-events/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about firecrawl-webhooks-events
How to install firecrawl-webhooks-events in Claude Code?
Run npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a claude-code in your terminal.
What does firecrawl-webhooks-events do?
It provides architectural rules to safely verify, acknowledge within 10 seconds, and process asynchronous Firecrawl webhook events.
How does the skill handle failed crawl jobs?
Because Firecrawl does not publish failure events for crawls or batch scrapes, the skill mandates polling documented job status APIs directly.
Source text
SKILL.md · MIT
--- name: firecrawl-webhooks-events description: >- Receive, verify, deduplicate, process, and reconcile current Firecrawl crawl, batch, extract, agent, and monitor webhooks. Use when building asynchronous event delivery. Trigger with "Firecrawl webhook", "X-Firecrawl-Signature", or "Firecrawl events". allowed-tools: Read,Glob,Grep,Write,Edit argument-hint: "<repository-path> <event-family>" version: 1.12.0 license: MIT author: Jeremy Longshore <[email protected]> tags: [saas, firecrawl, webhooks, security] model: inherit effort: high compatibility: "Designed for Claude Code; Firecrawl Cloud work requires network access" --- # Firecrawl Signed Webhook Processing ## Overview Treat a webhook as an authenticated delivery hint into a durable state machine. Verify before parsing or side effects, acknowledge promptly, and reconcile through status APIs after missed delivery. ## Prerequisites - The target repository or integration path and the requested operator outcome. - The source authorization, data classification, and environment policy. - Current Firecrawl documentation, credentials only when needed, and an owner for approvals. ## Current Contract Firecrawl signs the raw request body with HMAC-SHA256 in X-Firecrawl-Signature formatted sha256=hex. The documented events are crawl.started/page/completed; batch_scrape.started/page/completed; extract.started/completed/failed; agent.started/action/completed/failed/cancelled; monitor.page and monitor.check.completed. Endpoints must return 2xx within 10 seconds; failed delivery retries after 1, 5, and 15 minutes, then stops. ## Authentication For authenticated Cloud operations, inject FIRECRAWL_API_KEY from an approved secret manager. REST requests use Authorization: Bearer with the key. Never print, commit, transmit, or place a key in a URL. Keyless access is suitable only where the current documentation explicitly allows it and the workload accepts its limits; production workflows should make identity and team ownership explicit. ## Instructions 1. Register an HTTPS endpoint and choose only the events required for the workflow. Store the account webhook secret in an approved secret manager. 2. Capture the raw body before any JSON parser. Require one X-Firecrawl-Signature value, split and validate the sha256 prefix, hex-decode safely, and compare equal-length digests timing-safely. 3. Reject missing, malformed, or mismatched signatures before parsing, logging, queuing, or mutating state. Never treat a missing secret as verification success. 4. Parse the verified envelope, allowlist exact event types and schema, bind it to the expected team/job, and deduplicate by webhookId plus event/job context. 5. Persist an inbox record and respond with 2xx inside the deadline; process content and downstream writes asynchronously with tenant isolation and idempotency. 6. Handle page and terminal events according to their documented family. Do not wait for nonexistent crawl.failed or batch_scrape.failed events; reconcile job status and pagination. 7. Test signatures, raw-body mutation, duplicates, reordering, retry timing, unknown events, partial pages, crash recovery, and status reconciliation. ## Tool Discipline Use Read, Glob, and Grep to inspect code, configuration, tests, and evidence. Use Write/Edit only for approved implementation or documentation changes. Do not call Firecrawl, rotate keys, change account settings, scrape a target, or deploy merely because this skill was invoked. ## Approval Boundaries Require approval before creating the endpoint, storing a webhook secret, adding custom webhook headers/metadata, retaining page payloads, replaying production events, or changing event filters. ## Output Return endpoint and event scope, secret reference, verification algorithm, schema/idempotency model, acknowledgment boundary, reconciliation path, test evidence, metrics, and replay/rollback controls. ## Error Handling - Signature or raw body is unavailable: return a non-2xx rejection and perform no side effect. - Processing fails after acknowledgment: retry from the durable inbox and reconcile provider state. - Retries are exhausted or a terminal event is missing: poll the documented job status and paginate results. ## Examples - "Add a crawl webhook" handles started/page/completed and reconciles status for failure. - "Skip verification when the secret is unset" is explicitly rejected. ## Resources Read [official Firecrawl evidence](references/official-docs.md) before relying on an endpoint, SDK method, plan limit, price, retention option, or self-hosted release.
© Jeremy Longshore · MIT · jeremylongshore/tons-of-skills-marketplace