Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add jeremylongshore/tons-of-skills-marketplace --skill firecrawl-webhooks-events -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/firecrawl-webhooks-events/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/firecrawl-webhooks-events/

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

Similar skills

All skills for Backend and APIs →

From the same set139

The whole set →
fireflies-webhooks-events fireflies-webhooks-events walks an agent through building a Fireflies Webhooks V2 receiver: raw-body HMAC check, event allowlisting, dedupe, and a 2xx reply fast enough for the 10-second window. CX Codex +1 1installs documenso-webhooks-events documenso-webhooks-events configures Documenso webhook endpoints and event handlers. Useful when tracking document signing status and automating downstream actions. CX Codex +1 1installs windsurf-webhooks-events The windsurf-webhooks-events skill guides you through building Windsurf extensions with the VS Code API and forwarding workspace events to an external service. Use it to track saves, editor changes, or terminal output. CX Codex +1 1installs twinmind-webhooks-events twinmind-webhooks-events — a skill for TwinMind meeting events: transcription completion, action item extraction, and calendar sync notifications. CX Codex +1 1installs coderabbit-webhooks-events coderabbit-webhooks-events is a Claude Code skill for designing Git-provider event automation around CodeRabbit reviews. It checks signatures and tests replay handling. CX Codex +1 1installs posthog-webhooks-events posthog-webhooks-events registers PostHog webhook destinations through the API, handles the incoming payloads, and runs bounded event queries with HogQL or the private API. CX Codex +1 1installs instantly-webhooks-events instantly-webhooks-events guides the setup and operation of Instantly API v2 webhooks with schema checks, deduplication, and privacy safeguards. CX Codex +1 1installs windsurf-data-handling The windsurf-data-handling skill maps data flows, sets context exclusions, and gathers evidence for privacy and compliance reviews around Devin Desktop, formerly Windsurf. CX Codex +1 1installs

Project sponsors

Companies that keep this analytics open