Skip to content
FairCrawl Docs

Webhooks

FairCrawl currently supports async callback delivery on routes that accept callback_url.

Current callback-aware routes

  • POST /v1/crawl/web/scrape
  • POST /v1/crawl/web/crawl
  • GET /v1/crawl/:platform/:action?callback_url=...
  • POST /v1/crawl/:platform/:action
  • POST /v1/crawl/enrich/company
  • POST /v1/crawl/enrich/contact
  • POST /v1/crawl/enrich/contacts

/map, /research, /interact, /agent, and the freshness endpoints are direct-response only today.

Scrape callback request

Terminal window
curl https://api.faircompany.ai/v1/crawl/web/scrape \
  -X POST \
  -H "Authorization: Bearer fc_live_xxx" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://stripe.com/pricing",
    "format": "markdown",
    "callback_url": "https://example.com/webhooks/faircrawl"
  }'

Example delivery payload

{
  "jobId": "crawl_job_123",
  "status": "completed",
  "text": "...",
  "_meta": {
    "requestId": "req_123",
    "platform": "web",
    "action": "scrape",
    "billing_action": "crawl.single",
    "cost": 0.0005,
    "method": "direct_fetch",
    "responseTimeMs": 842
  }
}

Delivery headers

Content-Type: application/json
X-FairCrawl-Job-Id: crawl_job_123
User-Agent: FairCrawl/1.0 Webhook
X-FairCrawl-Signature: <sha256 hex, when WEBHOOK_SIGNING_SECRET is configured>

Enrichment callback shape

Enrichment callbacks are job-oriented and return job_id, type, status, and either a result object or an error.