Source · Firecrawl · Verified November 1, 2026

Firecrawl

Short answer: Firecrawl lifecycle webhooks report crawl, batch scrape, extract, agent and monitor progress with page-level results.

Hooks verifies Firecrawl deliveries with hmac-sha256, lowercase hex, sha256= prefix over the raw body and normalizes them into the unified event format.

Set up the webhook in Firecrawl

  1. Create a crawl, batch scrape, extract, agent or monitor with a webhook object that points at your Hooks receive URL.
  2. Copy the account webhook secret from Firecrawl → Settings → Advanced into the Hooks source secret field; Firecrawl sends X-Firecrawl-Signature: sha256=<hex> over the raw body.
  3. Keep the default event list or subscribe to a subset. Retries at 1, 5 and 15 minutes reuse the same webhookId, so Hooks dedupes exact retries; the Firecrawl job id is never used as the delivery id.

Signature verification

HeaderX-Firecrawl-Signature
AlgorithmHMAC-SHA256, lowercase hex, sha256= prefix over the raw body
Replay windownone
Delivery idBody `webhookId`

Events Hooks normalizes

event.typesubjectWhat it means
crawl.pageeventFirecrawl lifecycle webhooks report crawl, batch scrape, extract, agent and monitor progress with page-level results.

Normalized payload

Every adapter produces this shape before filters or templates run. The raw payload and sanitized headers stay attached for audit, but filters and templates read the normalized fields.

Normalized event

{
  "id": "evt_demo",
  "source": "firecrawl",
  "type": "crawl.page",
  "action": "page",
  "deliveryId": "delivery_demo",
  "subject": {
    "title": "Firecrawl event"
  },
  "raw": {
    "success": true,
    "type": "crawl.page",
    "id": "019c2c3f-7d4e-7a11-9b3c-2f6d1e8a4c90",
    "webhookId": "019c2c40-1a2b-7c3d-8e4f-5a6b7c8d9e0f",
    "data": [
      {
        "markdown": "# Example page",
        "metadata": {
          "title": "Example page",
          "url": "https://example.com/pricing",
          "statusCode": 200,
          "scrapeId": "019c2c41-2b3c-7d4e-8f5a-6b7c8d9e0f1a"
        }
      }
    ],
    "metadata": {
      "environment": "production"
    }
  }
}

Filter and template examples

Filter

type equals "crawl.page"

Template

"Firecrawl event: {{event.subject.title}}"

Retries and the delivery log

408, 425, 429, and 5xx responses retry with backoff and honor Retry-After; other 4xx responses fail permanently with a named code. Every attempt keeps the rendered request and the target response, so a failure points at one field or one status instead of a guess.

Hooks delivery detail: attempt timeline, request payload, and the destination response for one delivery
Delivery detail: the attempt timeline, the rendered request the target received, and its response — the same record an event keeps for every destination.

Common errors

SymptomFix
SIGNATURE_INVALIDUse the signing secret Firecrawl shows when the webhook is created, and send X-Firecrawl-Signature for the exact raw body.
Nothing arrivesConfirm the webhook points at the endpoint's /in/<endpoint-id> URL and that the endpoint is active.

Pair with a target

Reference

Other sources