feat: add webhook support for /llm/job endpoint

Add comprehensive webhook notification support for the /llm/job endpoint,
following the same pattern as the existing /crawl/job implementation.

Changes:
- Add webhook_config field to LlmJobPayload model (job.py)
- Implement webhook notifications in process_llm_extraction() with 4
  notification points: success, provider validation failure, extraction
  failure, and general exceptions (api.py)
- Store webhook_config in Redis task data for job tracking
- Initialize WebhookDeliveryService with exponential backoff retry logic
Documentation:
- Add Example 6 to WEBHOOK_EXAMPLES.md showing LLM extraction with webhooks
- Update Flask webhook handler to support both crawl and llm_extraction tasks
- Add TypeScript client examples for LLM jobs
- Add comprehensive examples to docker_webhook_example.py with schema support
- Clarify data structure differences between webhook and API responses

Testing:
- Add test_llm_webhook_feature.py with 7 validation tests (all passing)
- Verify pattern consistency with /crawl/job implementation
- Add implementation guide (WEBHOOK_LLM_JOB_IMPLEMENTATION.md)

README.md

@@ -304,9 +304,9 @@ The new Docker implementation includes:
 ### Getting Started
 
 ```bash
-# Pull and run the latest release
-docker pull unclecode/crawl4ai:latest
-docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:latest
+# Pull and run the latest release candidate
+docker pull unclecode/crawl4ai:0.7.0
+docker run -d -p 11235:11235 --name crawl4ai --shm-size=1g unclecode/crawl4ai:0.7.0
 
 # Visit the playground at http://localhost:11235/playground
 ```
@@ -373,7 +373,7 @@ async def main():
     
     async with AsyncWebCrawler(config=browser_config) as crawler:
         result = await crawler.arun(
-            url="https://docs.micronaut.io/4.9.9/guide/",
+            url="https://docs.micronaut.io/4.7.6/guide/",
             config=run_config
         )
         print(len(result.markdown.raw_markdown))
@@ -425,7 +425,7 @@ async def main():
             "type": "attribute",
             "attribute": "src"
         }
-    ]
+    }
 }
 
     extraction_strategy = JsonCssExtractionStrategy(schema, verbose=True)
@@ -919,6 +919,36 @@ We envision a future where AI is powered by real human knowledge, ensuring data
 For more details, see our [full mission statement](./MISSION.md).
 </details>
 
+## 🌟 Current Sponsors
+
+### 🏢 Enterprise Sponsors & Partners
+
+Our enterprise sponsors and technology partners help scale Crawl4AI to power production-grade data pipelines.
+
+| Company | About | Sponsorship Tier |
+|------|------|----------------------------|
+| <a href="https://dashboard.capsolver.com/passport/register?inviteCode=ESVSECTX5Q23" target="_blank"><picture><source width="120" media="(prefers-color-scheme: dark)" srcset="https://docs.crawl4ai.com/uploads/sponsors/20251013045338_72a71fa4ee4d2f40.png"><source width="120" media="(prefers-color-scheme: light)" srcset="https://www.capsolver.com/assets/images/logo-text.png"><img alt="Capsolver" src="https://www.capsolver.com/assets/images/logo-text.png"></picture></a> | AI-powered Captcha solving service. Supports all major Captcha types, including reCAPTCHA, Cloudflare, and more | 🥈 Silver |
+| <a href="https://kipo.ai" target="_blank"><img src="https://docs.crawl4ai.com/uploads/sponsors/20251013045751_2d54f57f117c651e.png" alt="DataSync" width="120"/></a> | Helps engineers and buyers find, compare, and source electronic & industrial parts in seconds, with specs, pricing, lead times & alternatives.| 🥇 Gold |
+| <a href="https://www.kidocode.com/" target="_blank"><img src="https://docs.crawl4ai.com/uploads/sponsors/20251013045045_bb8dace3f0440d65.svg" alt="Kidocode" width="120"/><p align="center">KidoCode</p></a> | Kidocode is a hybrid technology and entrepreneurship school for kids aged 5–18, offering both online and on-campus education. | 🥇 Gold |
+| <a href="https://www.alephnull.sg/" target="_blank"><img src="https://docs.crawl4ai.com/uploads/sponsors/20251013050323_a9e8e8c4c3650421.svg" alt="Aleph null" width="120"/></a> | Singapore-based  Aleph Null is Asia’s leading edtech hub, dedicated to student-centric, AI-driven education—empowering learners with the tools to thrive in a fast-changing world. | 🥇 Gold |
+
+### 🧑‍🤝 Individual Sponsors
+
+A heartfelt thanks to our individual supporters! Every contribution helps us keep our opensource mission alive and thriving!
+
+<p align="left">
+  <a href="https://github.com/hafezparast"><img src="https://avatars.githubusercontent.com/u/14273305?s=60&v=4" style="border-radius:50%;" width="64px;"/></a>
+  <a href="https://github.com/ntohidi"><img src="https://avatars.githubusercontent.com/u/17140097?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/Sjoeborg"><img src="https://avatars.githubusercontent.com/u/17451310?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/romek-rozen"><img src="https://avatars.githubusercontent.com/u/30595969?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/Kourosh-Kiyani"><img src="https://avatars.githubusercontent.com/u/34105600?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/Etherdrake"><img src="https://avatars.githubusercontent.com/u/67021215?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/shaman247"><img src="https://avatars.githubusercontent.com/u/211010067?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+  <a href="https://github.com/work-flow-manager"><img src="https://avatars.githubusercontent.com/u/217665461?s=60&v=4" style="border-radius:50%;"width="64px;"/></a>
+</p>
+
+> Want to join them? [Sponsor Crawl4AI →](https://github.com/sponsors/unclecode)
+
 ## Star History
 
 [![Star History Chart](https://api.star-history.com/svg?repos=unclecode/crawl4ai&type=Date)](https://star-history.com/#unclecode/crawl4ai&Date)

crawl4ai/async_configs.py

@@ -97,16 +97,13 @@ def to_serializable_dict(obj: Any, ignore_default_value : bool = False) -> Dict:
                 if value != param.default and not ignore_default_value:
                     current_values[name] = to_serializable_dict(value)
         
-        # Don't serialize private __slots__ - they're internal implementation details
-        # not constructor parameters. This was causing URLPatternFilter to fail
-        # because _simple_suffixes was being serialized as 'simple_suffixes'
-        # if hasattr(obj, '__slots__'):
-        #     for slot in obj.__slots__:
-        #         if slot.startswith('_'):  # Handle private slots
-        #             attr_name = slot[1:]  # Remove leading '_'
-        #             value = getattr(obj, slot, None)
-        #             if value is not None:
-        #                 current_values[attr_name] = to_serializable_dict(value)
+        if hasattr(obj, '__slots__'):
+            for slot in obj.__slots__:
+                if slot.startswith('_'):  # Handle private slots
+                    attr_name = slot[1:]  # Remove leading '_'
+                    value = getattr(obj, slot, None)
+                    if value is not None:
+                        current_values[attr_name] = to_serializable_dict(value)
 
             
         

crawl4ai/async_crawler_strategy.back.py

@@ -824,7 +824,7 @@ class AsyncPlaywrightCrawlerStrategy(AsyncCrawlerStrategy):
             except Error:
                 visibility_info = await self.check_visibility(page)
 
-                if self.browser_config.verbose:
+                if self.browser_config.config.verbose:
                     self.logger.debug(
                         message="Body visibility info: {info}",
                         tag="DEBUG",

crawl4ai/deep_crawling/bff_strategy.py

@@ -47,13 +47,7 @@ class BestFirstCrawlingStrategy(DeepCrawlStrategy):
         self.url_scorer = url_scorer
         self.include_external = include_external
         self.max_pages = max_pages
-        # self.logger = logger or logging.getLogger(__name__)
-        # Ensure logger is always a Logger instance, not a dict from serialization
-        if isinstance(logger, logging.Logger):
-            self.logger = logger
-        else:
-            # Create a new logger if logger is None, dict, or any other non-Logger type
-            self.logger = logging.getLogger(__name__)
+        self.logger = logger or logging.getLogger(__name__)
         self.stats = TraversalStats(start_time=datetime.now())
         self._cancel_event = asyncio.Event()
         self._pages_crawled = 0

crawl4ai/deep_crawling/bfs_strategy.py

@@ -38,13 +38,7 @@ class BFSDeepCrawlStrategy(DeepCrawlStrategy):
         self.include_external = include_external
         self.score_threshold = score_threshold
         self.max_pages = max_pages
-        # self.logger = logger or logging.getLogger(__name__)
-        # Ensure logger is always a Logger instance, not a dict from serialization
-        if isinstance(logger, logging.Logger):
-            self.logger = logger
-        else:
-            # Create a new logger if logger is None, dict, or any other non-Logger type
-            self.logger = logging.getLogger(__name__)
+        self.logger = logger or logging.getLogger(__name__)
         self.stats = TraversalStats(start_time=datetime.now())
         self._cancel_event = asyncio.Event()
         self._pages_crawled = 0

crawl4ai/deep_crawling/filters.py

@@ -120,9 +120,6 @@ class URLPatternFilter(URLFilter):
     """Pattern filter balancing speed and completeness"""
 
     __slots__ = (
-        "patterns",  # Store original patterns for serialization
-        "use_glob",  # Store original use_glob for serialization  
-        "reverse",   # Store original reverse for serialization
         "_simple_suffixes",
         "_simple_prefixes",
         "_domain_patterns",
@@ -145,11 +142,6 @@ class URLPatternFilter(URLFilter):
         reverse: bool = False,
     ):
         super().__init__()
-        # Store original constructor params for serialization
-        self.patterns = patterns
-        self.use_glob = use_glob
-        self.reverse = reverse
-        
         self._reverse = reverse
         patterns = [patterns] if isinstance(patterns, (str, Pattern)) else patterns
 

crawl4ai/models.py

@@ -253,16 +253,6 @@ class CrawlResult(BaseModel):
         requirements change, this is where you would update the logic.
         """
         result = super().model_dump(*args, **kwargs)
-        
-        # Remove any property descriptors that might have been included
-        # These deprecated properties should not be in the serialized output
-        for key in ['fit_html', 'fit_markdown', 'markdown_v2']:
-            if key in result and isinstance(result[key], property):
-                # del result[key]
-                # Nasrin: I decided to convert it to string instead of removing it.
-                result[key] = str(result[key])
-        
-        # Add the markdown field properly
         if self._markdown is not None:
             result["markdown"] = self._markdown.model_dump() 
         return result

crawl4ai/utils.py

@@ -2184,10 +2184,8 @@ def normalize_url(
     netloc = parsed.netloc.lower()
 
     # ── path ──
-    # Strip duplicate slashes and trailing "/" (except root)
-    # IMPORTANT: Don't use quote(unquote()) as it mangles + signs in URLs
-    # The path from urlparse is already properly encoded
-    path = parsed.path
+    # Strip duplicate slashes and trailing “/” (except root)
+    path = quote(unquote(parsed.path))
     if path.endswith('/') and path != '/':
         path = path.rstrip('/')
 

deploy/docker/.llm.env.example

@@ -10,23 +10,4 @@ GEMINI_API_TOKEN=your_gemini_key_here
 # Optional: Override the default LLM provider
 # Examples: "openai/gpt-4", "anthropic/claude-3-opus", "deepseek/chat", etc.
 # If not set, uses the provider specified in config.yml (default: openai/gpt-4o-mini)
-# LLM_PROVIDER=anthropic/claude-3-opus
-
-# Optional: Global LLM temperature setting (0.0-2.0)
-# Controls randomness in responses. Lower = more focused, Higher = more creative
-# LLM_TEMPERATURE=0.7
-
-# Optional: Global custom API base URL
-# Use this to point to custom endpoints or proxy servers
-# LLM_BASE_URL=https://api.custom.com/v1
-
-# Optional: Provider-specific temperature overrides
-# These take precedence over the global LLM_TEMPERATURE
-# OPENAI_TEMPERATURE=0.5
-# ANTHROPIC_TEMPERATURE=0.3
-# GROQ_TEMPERATURE=0.8
-
-# Optional: Provider-specific base URL overrides
-# Use for provider-specific proxy endpoints
-# OPENAI_BASE_URL=https://custom-openai.company.com/v1
-# GROQ_BASE_URL=https://custom-groq.company.com/v1
+# LLM_PROVIDER=anthropic/claude-3-opus

deploy/docker/README.md

@@ -12,6 +12,7 @@
   - [Python SDK](#python-sdk)
   - [Understanding Request Schema](#understanding-request-schema)
   - [REST API Examples](#rest-api-examples)
+  - [Asynchronous Jobs with Webhooks](#asynchronous-jobs-with-webhooks)
 - [Additional API Endpoints](#additional-api-endpoints)
   - [HTML Extraction Endpoint](#html-extraction-endpoint)
   - [Screenshot Endpoint](#screenshot-endpoint)
@@ -648,6 +649,146 @@ async def test_stream_crawl(token: str = None): # Made token optional
 # asyncio.run(test_stream_crawl())
 ```
 
+### Asynchronous Jobs with Webhooks
+
+For long-running crawls or when you want to avoid keeping connections open, use the job queue endpoints. Instead of polling for results, configure a webhook to receive notifications when jobs complete.
+
+#### Why Use Jobs & Webhooks?
+
+- **No Polling Required** - Get notified when crawls complete instead of constantly checking status
+- **Better Resource Usage** - Free up client connections while jobs run in the background
+- **Scalable Architecture** - Ideal for high-volume crawling with TypeScript/Node.js clients or microservices
+- **Reliable Delivery** - Automatic retry with exponential backoff (5 attempts: 1s → 2s → 4s → 8s → 16s)
+
+#### How It Works
+
+1. **Submit Job** → POST to `/crawl/job` with optional `webhook_config`
+2. **Get Task ID** → Receive a `task_id` immediately
+3. **Job Runs** → Crawl executes in the background
+4. **Webhook Fired** → Server POSTs completion notification to your webhook URL
+5. **Fetch Results** → If data wasn't included in webhook, GET `/crawl/job/{task_id}`
+
+#### Quick Example
+
+```bash
+# Submit a crawl job with webhook notification
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"],
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/crawl-complete",
+      "webhook_data_in_payload": false
+    }
+  }'
+
+# Response: {"task_id": "crawl_a1b2c3d4"}
+```
+
+**Your webhook receives:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4",
+  "task_type": "crawl",
+  "status": "completed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com"]
+}
+```
+
+Then fetch the results:
+```bash
+curl http://localhost:11235/crawl/job/crawl_a1b2c3d4
+```
+
+#### Include Data in Webhook
+
+Set `webhook_data_in_payload: true` to receive the full crawl results directly in the webhook:
+
+```bash
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"],
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/crawl-complete",
+      "webhook_data_in_payload": true
+    }
+  }'
+```
+
+**Your webhook receives the complete data:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4",
+  "task_type": "crawl",
+  "status": "completed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com"],
+  "data": {
+    "markdown": "...",
+    "html": "...",
+    "links": {...},
+    "metadata": {...}
+  }
+}
+```
+
+#### Webhook Authentication
+
+Add custom headers for authentication:
+
+```json
+{
+  "urls": ["https://example.com"],
+  "webhook_config": {
+    "webhook_url": "https://myapp.com/webhooks/crawl",
+    "webhook_data_in_payload": false,
+    "webhook_headers": {
+      "X-Webhook-Secret": "your-secret-token",
+      "X-Service-ID": "crawl4ai-prod"
+    }
+  }
+}
+```
+
+#### Global Default Webhook
+
+Configure a default webhook URL in `config.yml` for all jobs:
+
+```yaml
+webhooks:
+  enabled: true
+  default_url: "https://myapp.com/webhooks/default"
+  data_in_payload: false
+  retry:
+    max_attempts: 5
+    initial_delay_ms: 1000
+    max_delay_ms: 32000
+    timeout_ms: 30000
+```
+
+Now jobs without `webhook_config` automatically use the default webhook.
+
+#### Job Status Polling (Without Webhooks)
+
+If you prefer polling instead of webhooks, just omit `webhook_config`:
+
+```bash
+# Submit job
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{"urls": ["https://example.com"]}'
+# Response: {"task_id": "crawl_xyz"}
+
+# Poll for status
+curl http://localhost:11235/crawl/job/crawl_xyz
+```
+
+The response includes `status` field: `"processing"`, `"completed"`, or `"failed"`.
+
+> 💡 **Pro tip**: See [WEBHOOK_EXAMPLES.md](./WEBHOOK_EXAMPLES.md) for detailed examples including TypeScript client code, Flask webhook handlers, and failure handling.
+
 ---
 
 ## Metrics & Monitoring
@@ -692,7 +833,8 @@ app:
 # Default LLM Configuration
 llm:
   provider: "openai/gpt-4o-mini"  # Can be overridden by LLM_PROVIDER env var
-  # api_key: sk-...  # If you pass the API key directly (not recommended)
+  api_key_env: "OPENAI_API_KEY"
+  # api_key: sk-...  # If you pass the API key directly then api_key_env will be ignored
 
 # Redis Configuration (Used by internal Redis server managed by supervisord)
 redis:
@@ -826,10 +968,11 @@ We're here to help you succeed with Crawl4AI! Here's how to get support:
 
 In this guide, we've covered everything you need to get started with Crawl4AI's Docker deployment:
 - Building and running the Docker container
-- Configuring the environment  
+- Configuring the environment
 - Using the interactive playground for testing
 - Making API requests with proper typing
 - Using the Python SDK
+- Asynchronous job queues with webhook notifications
 - Leveraging specialized endpoints for screenshots, PDFs, and JavaScript execution
 - Connecting via the Model Context Protocol (MCP)
 - Monitoring your deployment

deploy/docker/WEBHOOK_EXAMPLES.md

@@ -0,0 +1,378 @@
+# Webhook Feature Examples
+
+This document provides examples of how to use the webhook feature for crawl jobs in Crawl4AI.
+
+## Overview
+
+The webhook feature allows you to receive notifications when crawl jobs complete, eliminating the need for polling. Webhooks are sent with exponential backoff retry logic to ensure reliable delivery.
+
+## Configuration
+
+### Global Configuration (config.yml)
+
+You can configure default webhook settings in `config.yml`:
+
+```yaml
+webhooks:
+  enabled: true
+  default_url: null  # Optional: default webhook URL for all jobs
+  data_in_payload: false  # Optional: default behavior for including data
+  retry:
+    max_attempts: 5
+    initial_delay_ms: 1000  # 1s, 2s, 4s, 8s, 16s exponential backoff
+    max_delay_ms: 32000
+    timeout_ms: 30000  # 30s timeout per webhook call
+  headers:  # Optional: default headers to include
+    User-Agent: "Crawl4AI-Webhook/1.0"
+```
+
+## API Usage Examples
+
+### Example 1: Basic Webhook (Notification Only)
+
+Send a webhook notification without including the crawl data in the payload.
+
+**Request:**
+```bash
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"],
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/crawl-complete",
+      "webhook_data_in_payload": false
+    }
+  }'
+```
+
+**Response:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4"
+}
+```
+
+**Webhook Payload Received:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4",
+  "task_type": "crawl",
+  "status": "completed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com"]
+}
+```
+
+Your webhook handler should then fetch the results:
+```bash
+curl http://localhost:11235/crawl/job/crawl_a1b2c3d4
+```
+
+### Example 2: Webhook with Data Included
+
+Include the full crawl results in the webhook payload.
+
+**Request:**
+```bash
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"],
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/crawl-complete",
+      "webhook_data_in_payload": true
+    }
+  }'
+```
+
+**Webhook Payload Received:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4",
+  "task_type": "crawl",
+  "status": "completed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com"],
+  "data": {
+    "markdown": "...",
+    "html": "...",
+    "links": {...},
+    "metadata": {...}
+  }
+}
+```
+
+### Example 3: Webhook with Custom Headers
+
+Include custom headers for authentication or identification.
+
+**Request:**
+```bash
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"],
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/crawl-complete",
+      "webhook_data_in_payload": false,
+      "webhook_headers": {
+        "X-Webhook-Secret": "my-secret-token",
+        "X-Service-ID": "crawl4ai-production"
+      }
+    }
+  }'
+```
+
+The webhook will be sent with these additional headers plus the default headers from config.
+
+### Example 4: Failure Notification
+
+When a crawl job fails, a webhook is sent with error details.
+
+**Webhook Payload on Failure:**
+```json
+{
+  "task_id": "crawl_a1b2c3d4",
+  "task_type": "crawl",
+  "status": "failed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com"],
+  "error": "Connection timeout after 30s"
+}
+```
+
+### Example 5: Using Global Default Webhook
+
+If you set a `default_url` in config.yml, jobs without webhook_config will use it:
+
+**config.yml:**
+```yaml
+webhooks:
+  enabled: true
+  default_url: "https://myapp.com/webhooks/default"
+  data_in_payload: false
+```
+
+**Request (no webhook_config needed):**
+```bash
+curl -X POST http://localhost:11235/crawl/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "urls": ["https://example.com"]
+  }'
+```
+
+The webhook will be sent to the default URL configured in config.yml.
+
+### Example 6: LLM Extraction Job with Webhook
+
+Use webhooks with the LLM extraction endpoint for asynchronous processing.
+
+**Request:**
+```bash
+curl -X POST http://localhost:11235/llm/job \
+  -H "Content-Type: application/json" \
+  -d '{
+    "url": "https://example.com/article",
+    "q": "Extract the article title, author, and publication date",
+    "schema": "{\"type\": \"object\", \"properties\": {\"title\": {\"type\": \"string\"}, \"author\": {\"type\": \"string\"}, \"date\": {\"type\": \"string\"}}}",
+    "cache": false,
+    "provider": "openai/gpt-4o-mini",
+    "webhook_config": {
+      "webhook_url": "https://myapp.com/webhooks/llm-complete",
+      "webhook_data_in_payload": true
+    }
+  }'
+```
+
+**Response:**
+```json
+{
+  "task_id": "llm_1698765432_12345"
+}
+```
+
+**Webhook Payload Received:**
+```json
+{
+  "task_id": "llm_1698765432_12345",
+  "task_type": "llm_extraction",
+  "status": "completed",
+  "timestamp": "2025-10-21T10:30:00.000000+00:00",
+  "urls": ["https://example.com/article"],
+  "data": {
+    "extracted_content": {
+      "title": "Understanding Web Scraping",
+      "author": "John Doe",
+      "date": "2025-10-21"
+    }
+  }
+}
+```
+
+## Webhook Handler Example
+
+Here's a simple Python Flask webhook handler that supports both crawl and LLM extraction jobs:
+
+```python
+from flask import Flask, request, jsonify
+import requests
+
+app = Flask(__name__)
+
+@app.route('/webhooks/crawl-complete', methods=['POST'])
+def handle_crawl_webhook():
+    payload = request.json
+
+    task_id = payload['task_id']
+    task_type = payload['task_type']
+    status = payload['status']
+
+    if status == 'completed':
+        # If data not in payload, fetch it
+        if 'data' not in payload:
+            # Determine endpoint based on task type
+            endpoint = 'crawl' if task_type == 'crawl' else 'llm'
+            response = requests.get(f'http://localhost:11235/{endpoint}/job/{task_id}')
+            data = response.json()
+        else:
+            data = payload['data']
+
+        # Process based on task type
+        if task_type == 'crawl':
+            print(f"Processing crawl results for {task_id}")
+            # Handle crawl results
+            results = data.get('results', [])
+            for result in results:
+                print(f"  - {result.get('url')}: {len(result.get('markdown', ''))} chars")
+
+        elif task_type == 'llm_extraction':
+            print(f"Processing LLM extraction for {task_id}")
+            # Handle LLM extraction
+            # Note: Webhook sends 'extracted_content', API returns 'result'
+            extracted = data.get('extracted_content', data.get('result', {}))
+            print(f"  - Extracted: {extracted}")
+
+        # Your business logic here...
+
+    elif status == 'failed':
+        error = payload.get('error', 'Unknown error')
+        print(f"{task_type} job {task_id} failed: {error}")
+        # Handle failure...
+
+    return jsonify({"status": "received"}), 200
+
+if __name__ == '__main__':
+    app.run(port=8080)
+```
+
+## Retry Logic
+
+The webhook delivery service uses exponential backoff retry logic:
+
+- **Attempts:** Up to 5 attempts by default
+- **Delays:** 1s → 2s → 4s → 8s → 16s
+- **Timeout:** 30 seconds per attempt
+- **Retry Conditions:**
+  - Server errors (5xx status codes)
+  - Network errors
+  - Timeouts
+- **No Retry:**
+  - Client errors (4xx status codes)
+  - Successful delivery (2xx status codes)
+
+## Benefits
+
+1. **No Polling Required** - Eliminates constant API calls to check job status
+2. **Real-time Notifications** - Immediate notification when jobs complete
+3. **Reliable Delivery** - Exponential backoff ensures webhooks are delivered
+4. **Flexible** - Choose between notification-only or full data delivery
+5. **Secure** - Support for custom headers for authentication
+6. **Configurable** - Global defaults or per-job configuration
+7. **Universal Support** - Works with both `/crawl/job` and `/llm/job` endpoints
+
+## TypeScript Client Example
+
+```typescript
+interface WebhookConfig {
+  webhook_url: string;
+  webhook_data_in_payload?: boolean;
+  webhook_headers?: Record<string, string>;
+}
+
+interface CrawlJobRequest {
+  urls: string[];
+  browser_config?: Record<string, any>;
+  crawler_config?: Record<string, any>;
+  webhook_config?: WebhookConfig;
+}
+
+interface LLMJobRequest {
+  url: string;
+  q: string;
+  schema?: string;
+  cache?: boolean;
+  provider?: string;
+  webhook_config?: WebhookConfig;
+}
+
+async function createCrawlJob(request: CrawlJobRequest) {
+  const response = await fetch('http://localhost:11235/crawl/job', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(request)
+  });
+
+  const { task_id } = await response.json();
+  return task_id;
+}
+
+async function createLLMJob(request: LLMJobRequest) {
+  const response = await fetch('http://localhost:11235/llm/job', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify(request)
+  });
+
+  const { task_id } = await response.json();
+  return task_id;
+}
+
+// Usage - Crawl Job
+const crawlTaskId = await createCrawlJob({
+  urls: ['https://example.com'],
+  webhook_config: {
+    webhook_url: 'https://myapp.com/webhooks/crawl-complete',
+    webhook_data_in_payload: false,
+    webhook_headers: {
+      'X-Webhook-Secret': 'my-secret'
+    }
+  }
+});
+
+// Usage - LLM Extraction Job
+const llmTaskId = await createLLMJob({
+  url: 'https://example.com/article',
+  q: 'Extract the main points from this article',
+  provider: 'openai/gpt-4o-mini',
+  webhook_config: {
+    webhook_url: 'https://myapp.com/webhooks/llm-complete',
+    webhook_data_in_payload: true,
+    webhook_headers: {
+      'X-Webhook-Secret': 'my-secret'
+    }
+  }
+});
+```
+
+## Monitoring and Debugging
+
+Webhook delivery attempts are logged at INFO level:
+- Successful deliveries
+- Retry attempts with delays
+- Final failures after max attempts
+
+Check the application logs for webhook delivery status:
+```bash
+docker logs crawl4ai-container | grep -i webhook
+```

deploy/docker/api.py

@@ -4,7 +4,7 @@ import asyncio
 from typing import List, Tuple, Dict
 from functools import partial
 from uuid import uuid4
-from datetime import datetime, timezone
+from datetime import datetime
 from base64 import b64encode
 
 import logging
@@ -42,10 +42,9 @@ from utils import (
     should_cleanup_task,
     decode_redis_hash,
     get_llm_api_key,
-    validate_llm_provider,
-    get_llm_temperature,
-    get_llm_base_url
+    validate_llm_provider
 )
+from webhook import WebhookDeliveryService
 
 import psutil, time
 
@@ -98,9 +97,7 @@ async def handle_llm_qa(
         response = perform_completion_with_backoff(
             provider=config["llm"]["provider"],
             prompt_with_variables=prompt,
-            api_token=get_llm_api_key(config),  # Returns None to let litellm handle it
-            temperature=get_llm_temperature(config),
-            base_url=get_llm_base_url(config)
+            api_token=get_llm_api_key(config)
         )
 
         return response.choices[0].message.content
@@ -120,10 +117,12 @@ async def process_llm_extraction(
     schema: Optional[str] = None,
     cache: str = "0",
     provider: Optional[str] = None,
-    temperature: Optional[float] = None,
-    base_url: Optional[str] = None
+    webhook_config: Optional[Dict] = None
 ) -> None:
     """Process LLM extraction in background."""
+    # Initialize webhook service
+    webhook_service = WebhookDeliveryService(config)
+
     try:
         # Validate provider
         is_valid, error_msg = validate_llm_provider(config, provider)
@@ -132,14 +131,22 @@ async def process_llm_extraction(
                 "status": TaskStatus.FAILED,
                 "error": error_msg
             })
+
+            # Send webhook notification on failure
+            await webhook_service.notify_job_completion(
+                task_id=task_id,
+                task_type="llm_extraction",
+                status="failed",
+                urls=[url],
+                webhook_config=webhook_config,
+                error=error_msg
+            )
             return
-        api_key = get_llm_api_key(config, provider)  # Returns None to let litellm handle it
+        api_key = get_llm_api_key(config, provider)
         llm_strategy = LLMExtractionStrategy(
             llm_config=LLMConfig(
                 provider=provider or config["llm"]["provider"],
-                api_token=api_key,
-                temperature=temperature or get_llm_temperature(config, provider),
-                base_url=base_url or get_llm_base_url(config, provider)
+                api_token=api_key
             ),
             instruction=instruction,
             schema=json.loads(schema) if schema else None,
@@ -162,17 +169,40 @@ async def process_llm_extraction(
                 "status": TaskStatus.FAILED,
                 "error": result.error_message
             })
+
+            # Send webhook notification on failure
+            await webhook_service.notify_job_completion(
+                task_id=task_id,
+                task_type="llm_extraction",
+                status="failed",
+                urls=[url],
+                webhook_config=webhook_config,
+                error=result.error_message
+            )
             return
 
         try:
             content = json.loads(result.extracted_content)
         except json.JSONDecodeError:
             content = result.extracted_content
+
+        result_data = {"extracted_content": content}
+
         await redis.hset(f"task:{task_id}", mapping={
             "status": TaskStatus.COMPLETED,
             "result": json.dumps(content)
         })
 
+        # Send webhook notification on successful completion
+        await webhook_service.notify_job_completion(
+            task_id=task_id,
+            task_type="llm_extraction",
+            status="completed",
+            urls=[url],
+            webhook_config=webhook_config,
+            result=result_data
+        )
+
     except Exception as e:
         logger.error(f"LLM extraction error: {str(e)}", exc_info=True)
         await redis.hset(f"task:{task_id}", mapping={
@@ -180,15 +210,23 @@ async def process_llm_extraction(
             "error": str(e)
         })
 
+        # Send webhook notification on failure
+        await webhook_service.notify_job_completion(
+            task_id=task_id,
+            task_type="llm_extraction",
+            status="failed",
+            urls=[url],
+            webhook_config=webhook_config,
+            error=str(e)
+        )
+
 async def handle_markdown_request(
     url: str,
     filter_type: FilterType,
     query: Optional[str] = None,
     cache: str = "0",
     config: Optional[dict] = None,
-    provider: Optional[str] = None,
-    temperature: Optional[float] = None,
-    base_url: Optional[str] = None
+    provider: Optional[str] = None
 ) -> str:
     """Handle markdown generation requests."""
     try:
@@ -213,9 +251,7 @@ async def handle_markdown_request(
                 FilterType.LLM: LLMContentFilter(
                     llm_config=LLMConfig(
                         provider=provider or config["llm"]["provider"],
-                        api_token=get_llm_api_key(config, provider),  # Returns None to let litellm handle it
-                        temperature=temperature or get_llm_temperature(config, provider),
-                        base_url=base_url or get_llm_base_url(config, provider)
+                        api_token=get_llm_api_key(config, provider),
                     ),
                     instruction=query or "Extract main content"
                 )
@@ -261,8 +297,7 @@ async def handle_llm_request(
     cache: str = "0",
     config: Optional[dict] = None,
     provider: Optional[str] = None,
-    temperature: Optional[float] = None,
-    api_base_url: Optional[str] = None
+    webhook_config: Optional[Dict] = None,
 ) -> JSONResponse:
     """Handle LLM extraction requests."""
     base_url = get_base_url(request)
@@ -294,8 +329,7 @@ async def handle_llm_request(
             base_url,
             config,
             provider,
-            temperature,
-            api_base_url
+            webhook_config
         )
 
     except Exception as e:
@@ -341,8 +375,7 @@ async def create_new_task(
     base_url: str,
     config: dict,
     provider: Optional[str] = None,
-    temperature: Optional[float] = None,
-    api_base_url: Optional[str] = None
+    webhook_config: Optional[Dict] = None
 ) -> JSONResponse:
     """Create and initialize a new task."""
     decoded_url = unquote(input_path)
@@ -351,12 +384,18 @@ async def create_new_task(
 
     from datetime import datetime
     task_id = f"llm_{int(datetime.now().timestamp())}_{id(background_tasks)}"
-    
-    await redis.hset(f"task:{task_id}", mapping={
+
+    task_data = {
         "status": TaskStatus.PROCESSING,
         "created_at": datetime.now().isoformat(),
         "url": decoded_url
-    })
+    }
+
+    # Store webhook config if provided
+    if webhook_config:
+        task_data["webhook_config"] = json.dumps(webhook_config)
+
+    await redis.hset(f"task:{task_id}", mapping=task_data)
 
     background_tasks.add_task(
         process_llm_extraction,
@@ -368,8 +407,7 @@ async def create_new_task(
         schema,
         cache,
         provider,
-        temperature,
-        api_base_url
+        webhook_config
     )
 
     return JSONResponse({
@@ -587,6 +625,7 @@ async def handle_crawl_job(
     browser_config: Dict,
     crawler_config: Dict,
     config: Dict,
+    webhook_config: Optional[Dict] = None,
 ) -> Dict:
     """
     Fire-and-forget version of handle_crawl_request.
@@ -594,13 +633,24 @@ async def handle_crawl_job(
     lets /crawl/job/{task_id} polling fetch the result.
     """
     task_id = f"crawl_{uuid4().hex[:8]}"
-    await redis.hset(f"task:{task_id}", mapping={
+
+    # Store task data in Redis
+    task_data = {
         "status": TaskStatus.PROCESSING,         # <-- keep enum values consistent
-        "created_at": datetime.now(timezone.utc).replace(tzinfo=None).isoformat(),
+        "created_at": datetime.utcnow().isoformat(),
         "url": json.dumps(urls),                 # store list as JSON string
         "result": "",
         "error": "",
-    })
+    }
+
+    # Store webhook config if provided
+    if webhook_config:
+        task_data["webhook_config"] = json.dumps(webhook_config)
+
+    await redis.hset(f"task:{task_id}", mapping=task_data)
+
+    # Initialize webhook service
+    webhook_service = WebhookDeliveryService(config)
 
     async def _runner():
         try:
@@ -614,6 +664,17 @@ async def handle_crawl_job(
                 "status": TaskStatus.COMPLETED,
                 "result": json.dumps(result),
             })
+
+            # Send webhook notification on successful completion
+            await webhook_service.notify_job_completion(
+                task_id=task_id,
+                task_type="crawl",
+                status="completed",
+                urls=urls,
+                webhook_config=webhook_config,
+                result=result
+            )
+
             await asyncio.sleep(5)  # Give Redis time to process the update
         except Exception as exc:
             await redis.hset(f"task:{task_id}", mapping={
@@ -621,5 +682,15 @@ async def handle_crawl_job(
                 "error": str(exc),
             })
 
+            # Send webhook notification on failure
+            await webhook_service.notify_job_completion(
+                task_id=task_id,
+                task_type="crawl",
+                status="failed",
+                urls=urls,
+                webhook_config=webhook_config,
+                error=str(exc)
+            )
+
     background_tasks.add_task(_runner)
     return {"task_id": task_id}

deploy/docker/auth.py

@@ -28,43 +28,25 @@ def create_access_token(data: dict, expires_delta: Optional[timedelta] = None) -
     signing_key = get_jwk_from_secret(SECRET_KEY)
     return instance.encode(to_encode, signing_key, alg='HS256')
 
-def verify_token(credentials: HTTPAuthorizationCredentials) -> Dict:
+def verify_token(credentials: HTTPAuthorizationCredentials = Depends(security)) -> Dict:
     """Verify the JWT token from the Authorization header."""
-    
-    if not credentials or not credentials.credentials:
-        raise HTTPException(
-            status_code=401, 
-            detail="No token provided",
-            headers={"WWW-Authenticate": "Bearer"}
-        )
-    
+
+    if credentials is None:
+        return None
     token = credentials.credentials
     verifying_key = get_jwk_from_secret(SECRET_KEY)
     try:
         payload = instance.decode(token, verifying_key, do_time_check=True, algorithms='HS256')
         return payload
-    except Exception as e:
-        raise HTTPException(
-            status_code=401, 
-            detail=f"Invalid or expired token: {str(e)}",
-            headers={"WWW-Authenticate": "Bearer"}
-        )
+    except Exception:
+        raise HTTPException(status_code=401, detail="Invalid or expired token")
 
 
 def get_token_dependency(config: Dict):
     """Return the token dependency if JWT is enabled, else a function that returns None."""
-    
+
     if config.get("security", {}).get("jwt_enabled", False):
-        def jwt_required(credentials: HTTPAuthorizationCredentials = Depends(security)) -> Dict:
-            """Enforce JWT authentication when enabled."""
-            if credentials is None:
-                raise HTTPException(
-                    status_code=401, 
-                    detail="Authentication required. Please provide a valid Bearer token.",
-                    headers={"WWW-Authenticate": "Bearer"}
-                )
-            return verify_token(credentials)
-        return jwt_required
+        return verify_token
     else:
         return lambda: None
 

deploy/docker/config.yml

@@ -11,7 +11,8 @@ app:
 # Default LLM Configuration
 llm:
   provider: "openai/gpt-4o-mini"
-  # api_key: sk-...  # If you pass the API key directly (not recommended)
+  api_key_env: "OPENAI_API_KEY"
+  # api_key: sk-...  # If you pass the API key directly then api_key_env will be ignored
 
 # Redis Configuration
 redis:
@@ -38,8 +39,8 @@ rate_limiting:
 
 # Security Configuration
 security:
-  enabled: false
-  jwt_enabled: false
+  enabled: false 
+  jwt_enabled: false 
   https_redirect: false
   trusted_hosts: ["*"]
   headers:
@@ -87,4 +88,17 @@ observability:
     enabled: True
     endpoint: "/metrics"
   health_check:
-    endpoint: "/health"
+    endpoint: "/health"
+
+# Webhook Configuration
+webhooks:
+  enabled: true
+  default_url: null  # Optional: default webhook URL for all jobs
+  data_in_payload: false  # Optional: default behavior for including data
+  retry:
+    max_attempts: 5
+    initial_delay_ms: 1000  # 1s, 2s, 4s, 8s, 16s exponential backoff
+    max_delay_ms: 32000
+    timeout_ms: 30000  # 30s timeout per webhook call
+  headers:  # Optional: default headers to include
+    User-Agent: "Crawl4AI-Webhook/1.0"

deploy/docker/job.py

@@ -12,6 +12,7 @@ from api import (
     handle_crawl_job,
     handle_task_status,
 )
+from schemas import WebhookConfig
 
 # ------------- dependency placeholders -------------
 _redis = None        # will be injected from server.py
@@ -37,14 +38,14 @@ class LlmJobPayload(BaseModel):
     schema: Optional[str] = None
     cache:  bool = False
     provider: Optional[str] = None
-    temperature: Optional[float] = None
-    base_url: Optional[str] = None
+    webhook_config: Optional[WebhookConfig] = None
 
 
 class CrawlJobPayload(BaseModel):
     urls:           list[HttpUrl]
     browser_config: Dict = {}
     crawler_config: Dict = {}
+    webhook_config: Optional[WebhookConfig] = None
 
 
 # ---------- LL​M job ---------------------------------------------------------
@@ -55,6 +56,10 @@ async def llm_job_enqueue(
         request: Request,
         _td: Dict = Depends(lambda: _token_dep()),   # late-bound dep
 ):
+    webhook_config = None
+    if payload.webhook_config:
+        webhook_config = payload.webhook_config.model_dump(mode='json')
+
     return await handle_llm_request(
         _redis,
         background_tasks,
@@ -65,8 +70,7 @@ async def llm_job_enqueue(
         cache=payload.cache,
         config=_config,
         provider=payload.provider,
-        temperature=payload.temperature,
-        api_base_url=payload.base_url,
+        webhook_config=webhook_config,
     )
 
 
@@ -86,6 +90,10 @@ async def crawl_job_enqueue(
         background_tasks: BackgroundTasks,
         _td: Dict = Depends(lambda: _token_dep()),
 ):
+    webhook_config = None
+    if payload.webhook_config:
+        webhook_config = payload.webhook_config.model_dump(mode='json')
+
     return await handle_crawl_job(
         _redis,
         background_tasks,
@@ -93,6 +101,7 @@ async def crawl_job_enqueue(
         payload.browser_config,
         payload.crawler_config,
         config=_config,
+        webhook_config=webhook_config,
     )
 
 

deploy/docker/requirements.txt

@@ -12,6 +12,6 @@ pydantic>=2.11
 rank-bm25==0.2.2
 anyio==4.9.0
 PyJWT==2.10.1
-mcp>=1.6.0
+mcp>=1.18.0
 websockets>=15.0.1
 httpx[http2]>=0.27.2

deploy/docker/schemas.py

@@ -1,6 +1,6 @@
 from typing import List, Optional, Dict
 from enum import Enum
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, HttpUrl
 from utils import FilterType
 
 
@@ -16,8 +16,6 @@ class MarkdownRequest(BaseModel):
     q:   Optional[str] = Field(None,  description="Query string used by BM25/LLM filters")
     c:   Optional[str] = Field("0",   description="Cache‑bust / revision counter")
     provider: Optional[str] = Field(None, description="LLM provider override (e.g., 'anthropic/claude-3-opus')")
-    temperature: Optional[float] = Field(None, description="LLM temperature override (0.0-2.0)")
-    base_url: Optional[str] = Field(None, description="LLM API base URL override")
 
 
 class RawCode(BaseModel):
@@ -41,4 +39,22 @@ class JSEndpointRequest(BaseModel):
     scripts: List[str] = Field(
         ...,
         description="List of separated JavaScript snippets to execute"
-    )
+    )
+
+
+class WebhookConfig(BaseModel):
+    """Configuration for webhook notifications."""
+    webhook_url: HttpUrl
+    webhook_data_in_payload: bool = False
+    webhook_headers: Optional[Dict[str, str]] = None
+
+
+class WebhookPayload(BaseModel):
+    """Payload sent to webhook endpoints."""
+    task_id: str
+    task_type: str  # "crawl", "llm_extraction", etc.
+    status: str  # "completed" or "failed"
+    timestamp: str  # ISO 8601 format
+    urls: List[str]
+    error: Optional[str] = None
+    data: Optional[Dict] = None  # Included only if webhook_data_in_payload=True

deploy/docker/server.py

@@ -241,8 +241,7 @@ async def get_markdown(
         raise HTTPException(
             400, "Invalid URL format. Must start with http://, https://, or for raw HTML (raw:, raw://)")
     markdown = await handle_markdown_request(
-        body.url, body.f, body.q, body.c, config, body.provider,
-        body.temperature, body.base_url
+        body.url, body.f, body.q, body.c, config, body.provider
     )
     return JSONResponse({
         "url": body.url,

deploy/docker/utils.py

@@ -71,7 +71,7 @@ def decode_redis_hash(hash_data: Dict[bytes, bytes]) -> Dict[str, str]:
 
 
 
-def get_llm_api_key(config: Dict, provider: Optional[str] = None) -> Optional[str]:
+def get_llm_api_key(config: Dict, provider: Optional[str] = None) -> str:
     """Get the appropriate API key based on the LLM provider.
     
     Args:
@@ -79,14 +79,19 @@ def get_llm_api_key(config: Dict, provider: Optional[str] = None) -> Optional[st
         provider: Optional provider override (e.g., "openai/gpt-4")
     
     Returns:
-        The API key if directly configured, otherwise None to let litellm handle it
+        The API key for the provider, or empty string if not found
     """
-    # Check if direct API key is configured (for backward compatibility)
+        
+    # Use provided provider or fall back to config
+    if not provider:
+        provider = config["llm"]["provider"]
+    
+    # Check if direct API key is configured
     if "api_key" in config["llm"]:
         return config["llm"]["api_key"]
     
-    # Return None - litellm will automatically find the right environment variable
-    return None
+    # Fall back to the configured api_key_env if no match
+    return os.environ.get(config["llm"].get("api_key_env", ""), "")
 
 
 def validate_llm_provider(config: Dict, provider: Optional[str] = None) -> tuple[bool, str]:
@@ -99,78 +104,19 @@ def validate_llm_provider(config: Dict, provider: Optional[str] = None) -> tuple
     Returns:
         Tuple of (is_valid, error_message)
     """
-    # If a direct API key is configured, validation passes
-    if "api_key" in config["llm"]:
-        return True, ""
+    # Use provided provider or fall back to config
+    if not provider:
+        provider = config["llm"]["provider"]
+    
+    # Get the API key for this provider
+    api_key = get_llm_api_key(config, provider)
+    
+    if not api_key:
+        return False, f"No API key found for provider '{provider}'. Please set the appropriate environment variable."
     
-    # Otherwise, trust that litellm will find the appropriate environment variable
-    # We can't easily validate this without reimplementing litellm's logic
     return True, ""
 
 
-def get_llm_temperature(config: Dict, provider: Optional[str] = None) -> Optional[float]:
-    """Get temperature setting based on the LLM provider.
-    
-    Priority order:
-    1. Provider-specific environment variable (e.g., OPENAI_TEMPERATURE)
-    2. Global LLM_TEMPERATURE environment variable
-    3. None (to use litellm/provider defaults)
-    
-    Args:
-        config: The application configuration dictionary
-        provider: Optional provider override (e.g., "openai/gpt-4")
-    
-    Returns:
-        The temperature setting if configured, otherwise None
-    """
-    # Check provider-specific temperature first
-    if provider:
-        provider_name = provider.split('/')[0].upper()
-        provider_temp = os.environ.get(f"{provider_name}_TEMPERATURE")
-        if provider_temp:
-            try:
-                return float(provider_temp)
-            except ValueError:
-                logging.warning(f"Invalid temperature value for {provider_name}: {provider_temp}")
-    
-    # Check global LLM_TEMPERATURE
-    global_temp = os.environ.get("LLM_TEMPERATURE")
-    if global_temp:
-        try:
-            return float(global_temp)
-        except ValueError:
-            logging.warning(f"Invalid global temperature value: {global_temp}")
-    
-    # Return None to use litellm/provider defaults
-    return None
-
-
-def get_llm_base_url(config: Dict, provider: Optional[str] = None) -> Optional[str]:
-    """Get base URL setting based on the LLM provider.
-    
-    Priority order:
-    1. Provider-specific environment variable (e.g., OPENAI_BASE_URL)
-    2. Global LLM_BASE_URL environment variable
-    3. None (to use default endpoints)
-    
-    Args:
-        config: The application configuration dictionary
-        provider: Optional provider override (e.g., "openai/gpt-4")
-    
-    Returns:
-        The base URL if configured, otherwise None
-    """
-    # Check provider-specific base URL first
-    if provider:
-        provider_name = provider.split('/')[0].upper()
-        provider_url = os.environ.get(f"{provider_name}_BASE_URL")
-        if provider_url:
-            return provider_url
-    
-    # Check global LLM_BASE_URL
-    return os.environ.get("LLM_BASE_URL")
-
-
 def verify_email_domain(email: str) -> bool:
     try:
         domain = email.split('@')[1]

deploy/docker/webhook.py

@@ -0,0 +1,159 @@
+"""
+Webhook delivery service for Crawl4AI.
+
+This module provides webhook notification functionality with exponential backoff retry logic.
+"""
+import asyncio
+import httpx
+import logging
+from typing import Dict, Optional
+from datetime import datetime, timezone
+
+logger = logging.getLogger(__name__)
+
+
+class WebhookDeliveryService:
+    """Handles webhook delivery with exponential backoff retry logic."""
+
+    def __init__(self, config: Dict):
+        """
+        Initialize the webhook delivery service.
+
+        Args:
+            config: Application configuration dictionary containing webhook settings
+        """
+        self.config = config.get("webhooks", {})
+        self.max_attempts = self.config.get("retry", {}).get("max_attempts", 5)
+        self.initial_delay = self.config.get("retry", {}).get("initial_delay_ms", 1000) / 1000
+        self.max_delay = self.config.get("retry", {}).get("max_delay_ms", 32000) / 1000
+        self.timeout = self.config.get("retry", {}).get("timeout_ms", 30000) / 1000
+
+    async def send_webhook(
+        self,
+        webhook_url: str,
+        payload: Dict,
+        headers: Optional[Dict[str, str]] = None
+    ) -> bool:
+        """
+        Send webhook with exponential backoff retry logic.
+
+        Args:
+            webhook_url: The URL to send the webhook to
+            payload: The JSON payload to send
+            headers: Optional custom headers
+
+        Returns:
+            bool: True if delivered successfully, False otherwise
+        """
+        default_headers = self.config.get("headers", {})
+        merged_headers = {**default_headers, **(headers or {})}
+        merged_headers["Content-Type"] = "application/json"
+
+        async with httpx.AsyncClient(timeout=self.timeout) as client:
+            for attempt in range(self.max_attempts):
+                try:
+                    logger.info(
+                        f"Sending webhook (attempt {attempt + 1}/{self.max_attempts}) to {webhook_url}"
+                    )
+
+                    response = await client.post(
+                        webhook_url,
+                        json=payload,
+                        headers=merged_headers
+                    )
+
+                    # Success or client error (don't retry client errors)
+                    if response.status_code < 500:
+                        if 200 <= response.status_code < 300:
+                            logger.info(f"Webhook delivered successfully to {webhook_url}")
+                            return True
+                        else:
+                            logger.warning(
+                                f"Webhook rejected with status {response.status_code}: {response.text[:200]}"
+                            )
+                            return False  # Client error - don't retry
+
+                    # Server error - retry with backoff
+                    logger.warning(
+                        f"Webhook failed with status {response.status_code}, will retry"
+                    )
+
+                except httpx.TimeoutException as exc:
+                    logger.error(f"Webhook timeout (attempt {attempt + 1}): {exc}")
+                except httpx.RequestError as exc:
+                    logger.error(f"Webhook request error (attempt {attempt + 1}): {exc}")
+                except Exception as exc:
+                    logger.error(f"Webhook delivery error (attempt {attempt + 1}): {exc}")
+
+                # Calculate exponential backoff delay
+                if attempt < self.max_attempts - 1:
+                    delay = min(self.initial_delay * (2 ** attempt), self.max_delay)
+                    logger.info(f"Retrying in {delay}s...")
+                    await asyncio.sleep(delay)
+
+        logger.error(
+            f"Webhook delivery failed after {self.max_attempts} attempts to {webhook_url}"
+        )
+        return False
+
+    async def notify_job_completion(
+        self,
+        task_id: str,
+        task_type: str,
+        status: str,
+        urls: list,
+        webhook_config: Optional[Dict],
+        result: Optional[Dict] = None,
+        error: Optional[str] = None
+    ):
+        """
+        Notify webhook of job completion.
+
+        Args:
+            task_id: The task identifier
+            task_type: Type of task (e.g., "crawl", "llm_extraction")
+            status: Task status ("completed" or "failed")
+            urls: List of URLs that were crawled
+            webhook_config: Webhook configuration from the job request
+            result: Optional crawl result data
+            error: Optional error message if failed
+        """
+        # Determine webhook URL
+        webhook_url = None
+        data_in_payload = self.config.get("data_in_payload", False)
+        custom_headers = None
+
+        if webhook_config:
+            webhook_url = webhook_config.get("webhook_url")
+            data_in_payload = webhook_config.get("webhook_data_in_payload", data_in_payload)
+            custom_headers = webhook_config.get("webhook_headers")
+
+        if not webhook_url:
+            webhook_url = self.config.get("default_url")
+
+        if not webhook_url:
+            logger.debug("No webhook URL configured, skipping notification")
+            return
+
+        # Check if webhooks are enabled
+        if not self.config.get("enabled", True):
+            logger.debug("Webhooks are disabled, skipping notification")
+            return
+
+        # Build payload
+        payload = {
+            "task_id": task_id,
+            "task_type": task_type,
+            "status": status,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "urls": urls
+        }
+
+        if error:
+            payload["error"] = error
+
+        if data_in_payload and result:
+            payload["data"] = result
+
+        # Send webhook (fire and forget - don't block on completion)
+        await self.send_webhook(webhook_url, payload, custom_headers)

docs/examples/docker_webhook_example.py

@@ -0,0 +1,461 @@
+"""
+Docker Webhook Example for Crawl4AI
+
+This example demonstrates how to use webhooks with the Crawl4AI job queue API.
+Instead of polling for results, webhooks notify your application when jobs complete.
+
+Supports both:
+- /crawl/job - Raw crawling with markdown extraction
+- /llm/job - LLM-powered content extraction
+
+Prerequisites:
+1. Crawl4AI Docker container running on localhost:11234
+2. Flask installed: pip install flask requests
+3. LLM API key configured in .llm.env (for LLM extraction examples)
+
+Usage:
+1. Run this script: python docker_webhook_example.py
+2. The webhook server will start on http://localhost:8080
+3. Jobs will be submitted and webhooks will be received automatically
+"""
+
+import requests
+import json
+import time
+from flask import Flask, request, jsonify
+from threading import Thread
+
+# Configuration
+CRAWL4AI_BASE_URL = "http://localhost:11234"
+WEBHOOK_BASE_URL = "http://localhost:8080"  # Your webhook receiver URL
+
+# Initialize Flask app for webhook receiver
+app = Flask(__name__)
+
+# Store received webhook data for demonstration
+received_webhooks = []
+
+
+@app.route('/webhooks/crawl-complete', methods=['POST'])
+def handle_crawl_webhook():
+    """
+    Webhook handler that receives notifications when crawl jobs complete.
+
+    Payload structure:
+    {
+        "task_id": "crawl_abc123",
+        "task_type": "crawl",
+        "status": "completed" or "failed",
+        "timestamp": "2025-10-21T10:30:00.000000+00:00",
+        "urls": ["https://example.com"],
+        "error": "error message" (only if failed),
+        "data": {...} (only if webhook_data_in_payload=True)
+    }
+    """
+    payload = request.json
+    print(f"\n{'='*60}")
+    print(f"📬 Webhook received for task: {payload['task_id']}")
+    print(f"   Status: {payload['status']}")
+    print(f"   Timestamp: {payload['timestamp']}")
+    print(f"   URLs: {payload['urls']}")
+
+    if payload['status'] == 'completed':
+        # If data is in payload, process it directly
+        if 'data' in payload:
+            print(f"   ✅ Data included in webhook")
+            data = payload['data']
+            # Process the crawl results here
+            for result in data.get('results', []):
+                print(f"      - Crawled: {result.get('url')}")
+                print(f"      - Markdown length: {len(result.get('markdown', ''))}")
+        else:
+            # Fetch results from API if not included
+            print(f"   📥 Fetching results from API...")
+            task_id = payload['task_id']
+            result_response = requests.get(f"{CRAWL4AI_BASE_URL}/crawl/job/{task_id}")
+            if result_response.ok:
+                data = result_response.json()
+                print(f"   ✅ Results fetched successfully")
+                # Process the crawl results here
+                for result in data['result'].get('results', []):
+                    print(f"      - Crawled: {result.get('url')}")
+                    print(f"      - Markdown length: {len(result.get('markdown', ''))}")
+
+    elif payload['status'] == 'failed':
+        print(f"   ❌ Job failed: {payload.get('error', 'Unknown error')}")
+
+    print(f"{'='*60}\n")
+
+    # Store webhook for demonstration
+    received_webhooks.append(payload)
+
+    # Return 200 OK to acknowledge receipt
+    return jsonify({"status": "received"}), 200
+
+
+@app.route('/webhooks/llm-complete', methods=['POST'])
+def handle_llm_webhook():
+    """
+    Webhook handler that receives notifications when LLM extraction jobs complete.
+
+    Payload structure:
+    {
+        "task_id": "llm_1698765432_12345",
+        "task_type": "llm_extraction",
+        "status": "completed" or "failed",
+        "timestamp": "2025-10-21T10:30:00.000000+00:00",
+        "urls": ["https://example.com/article"],
+        "error": "error message" (only if failed),
+        "data": {"extracted_content": {...}} (only if webhook_data_in_payload=True)
+    }
+    """
+    payload = request.json
+    print(f"\n{'='*60}")
+    print(f"🤖 LLM Webhook received for task: {payload['task_id']}")
+    print(f"   Task Type: {payload['task_type']}")
+    print(f"   Status: {payload['status']}")
+    print(f"   Timestamp: {payload['timestamp']}")
+    print(f"   URL: {payload['urls'][0]}")
+
+    if payload['status'] == 'completed':
+        # If data is in payload, process it directly
+        if 'data' in payload:
+            print(f"   ✅ Data included in webhook")
+            data = payload['data']
+            # Webhook wraps extracted content in 'extracted_content' field
+            extracted = data.get('extracted_content', {})
+            print(f"      - Extracted content:")
+            print(f"        {json.dumps(extracted, indent=8)}")
+        else:
+            # Fetch results from API if not included
+            print(f"   📥 Fetching results from API...")
+            task_id = payload['task_id']
+            result_response = requests.get(f"{CRAWL4AI_BASE_URL}/llm/job/{task_id}")
+            if result_response.ok:
+                data = result_response.json()
+                print(f"   ✅ Results fetched successfully")
+                # API returns unwrapped content in 'result' field
+                extracted = data['result']
+                print(f"      - Extracted content:")
+                print(f"        {json.dumps(extracted, indent=8)}")
+
+    elif payload['status'] == 'failed':
+        print(f"   ❌ Job failed: {payload.get('error', 'Unknown error')}")
+
+    print(f"{'='*60}\n")
+
+    # Store webhook for demonstration
+    received_webhooks.append(payload)
+
+    # Return 200 OK to acknowledge receipt
+    return jsonify({"status": "received"}), 200
+
+
+def start_webhook_server():
+    """Start the Flask webhook server in a separate thread"""
+    app.run(host='0.0.0.0', port=8080, debug=False, use_reloader=False)
+
+
+def submit_crawl_job_with_webhook(urls, webhook_url, include_data=False):
+    """
+    Submit a crawl job with webhook notification.
+
+    Args:
+        urls: List of URLs to crawl
+        webhook_url: URL to receive webhook notifications
+        include_data: Whether to include full results in webhook payload
+
+    Returns:
+        task_id: The job's task identifier
+    """
+    payload = {
+        "urls": urls,
+        "browser_config": {"headless": True},
+        "crawler_config": {"cache_mode": "bypass"},
+        "webhook_config": {
+            "webhook_url": webhook_url,
+            "webhook_data_in_payload": include_data,
+            # Optional: Add custom headers for authentication
+            # "webhook_headers": {
+            #     "X-Webhook-Secret": "your-secret-token"
+            # }
+        }
+    }
+
+    print(f"\n🚀 Submitting crawl job...")
+    print(f"   URLs: {urls}")
+    print(f"   Webhook: {webhook_url}")
+    print(f"   Include data: {include_data}")
+
+    response = requests.post(
+        f"{CRAWL4AI_BASE_URL}/crawl/job",
+        json=payload,
+        headers={"Content-Type": "application/json"}
+    )
+
+    if response.ok:
+        data = response.json()
+        task_id = data['task_id']
+        print(f"   ✅ Job submitted successfully")
+        print(f"   Task ID: {task_id}")
+        return task_id
+    else:
+        print(f"   ❌ Failed to submit job: {response.text}")
+        return None
+
+
+def submit_llm_job_with_webhook(url, query, webhook_url, include_data=False, schema=None, provider=None):
+    """
+    Submit an LLM extraction job with webhook notification.
+
+    Args:
+        url: URL to extract content from
+        query: Instruction for the LLM (e.g., "Extract article title and author")
+        webhook_url: URL to receive webhook notifications
+        include_data: Whether to include full results in webhook payload
+        schema: Optional JSON schema for structured extraction
+        provider: Optional LLM provider (e.g., "openai/gpt-4o-mini")
+
+    Returns:
+        task_id: The job's task identifier
+    """
+    payload = {
+        "url": url,
+        "q": query,
+        "cache": False,
+        "webhook_config": {
+            "webhook_url": webhook_url,
+            "webhook_data_in_payload": include_data,
+            # Optional: Add custom headers for authentication
+            # "webhook_headers": {
+            #     "X-Webhook-Secret": "your-secret-token"
+            # }
+        }
+    }
+
+    if schema:
+        payload["schema"] = schema
+
+    if provider:
+        payload["provider"] = provider
+
+    print(f"\n🤖 Submitting LLM extraction job...")
+    print(f"   URL: {url}")
+    print(f"   Query: {query}")
+    print(f"   Webhook: {webhook_url}")
+    print(f"   Include data: {include_data}")
+    if provider:
+        print(f"   Provider: {provider}")
+
+    response = requests.post(
+        f"{CRAWL4AI_BASE_URL}/llm/job",
+        json=payload,
+        headers={"Content-Type": "application/json"}
+    )
+
+    if response.ok:
+        data = response.json()
+        task_id = data['task_id']
+        print(f"   ✅ Job submitted successfully")
+        print(f"   Task ID: {task_id}")
+        return task_id
+    else:
+        print(f"   ❌ Failed to submit job: {response.text}")
+        return None
+
+
+def submit_job_without_webhook(urls):
+    """
+    Submit a job without webhook (traditional polling approach).
+
+    Args:
+        urls: List of URLs to crawl
+
+    Returns:
+        task_id: The job's task identifier
+    """
+    payload = {
+        "urls": urls,
+        "browser_config": {"headless": True},
+        "crawler_config": {"cache_mode": "bypass"}
+    }
+
+    print(f"\n🚀 Submitting crawl job (without webhook)...")
+    print(f"   URLs: {urls}")
+
+    response = requests.post(
+        f"{CRAWL4AI_BASE_URL}/crawl/job",
+        json=payload
+    )
+
+    if response.ok:
+        data = response.json()
+        task_id = data['task_id']
+        print(f"   ✅ Job submitted successfully")
+        print(f"   Task ID: {task_id}")
+        return task_id
+    else:
+        print(f"   ❌ Failed to submit job: {response.text}")
+        return None
+
+
+def poll_job_status(task_id, timeout=60):
+    """
+    Poll for job status (used when webhook is not configured).
+
+    Args:
+        task_id: The job's task identifier
+        timeout: Maximum time to wait in seconds
+    """
+    print(f"\n⏳ Polling for job status...")
+    start_time = time.time()
+
+    while time.time() - start_time < timeout:
+        response = requests.get(f"{CRAWL4AI_BASE_URL}/crawl/job/{task_id}")
+
+        if response.ok:
+            data = response.json()
+            status = data.get('status', 'unknown')
+
+            if status == 'completed':
+                print(f"   ✅ Job completed!")
+                return data
+            elif status == 'failed':
+                print(f"   ❌ Job failed: {data.get('error', 'Unknown error')}")
+                return data
+            else:
+                print(f"   ⏳ Status: {status}, waiting...")
+                time.sleep(2)
+        else:
+            print(f"   ❌ Failed to get status: {response.text}")
+            return None
+
+    print(f"   ⏰ Timeout reached")
+    return None
+
+
+def main():
+    """Run the webhook demonstration"""
+
+    # Check if Crawl4AI is running
+    try:
+        health = requests.get(f"{CRAWL4AI_BASE_URL}/health", timeout=5)
+        print(f"✅ Crawl4AI is running: {health.json()}")
+    except:
+        print(f"❌ Cannot connect to Crawl4AI at {CRAWL4AI_BASE_URL}")
+        print("   Please make sure Docker container is running:")
+        print("   docker run -d -p 11234:11234 --name crawl4ai unclecode/crawl4ai:latest")
+        return
+
+    # Start webhook server in background thread
+    print(f"\n🌐 Starting webhook server at {WEBHOOK_BASE_URL}...")
+    webhook_thread = Thread(target=start_webhook_server, daemon=True)
+    webhook_thread.start()
+    time.sleep(2)  # Give server time to start
+
+    # Example 1: Job with webhook (notification only, fetch data separately)
+    print(f"\n{'='*60}")
+    print("Example 1: Webhook Notification Only")
+    print(f"{'='*60}")
+    task_id_1 = submit_crawl_job_with_webhook(
+        urls=["https://example.com"],
+        webhook_url=f"{WEBHOOK_BASE_URL}/webhooks/crawl-complete",
+        include_data=False
+    )
+
+    # Example 2: Job with webhook (data included in payload)
+    time.sleep(5)  # Wait a bit between requests
+    print(f"\n{'='*60}")
+    print("Example 2: Webhook with Full Data")
+    print(f"{'='*60}")
+    task_id_2 = submit_crawl_job_with_webhook(
+        urls=["https://www.python.org"],
+        webhook_url=f"{WEBHOOK_BASE_URL}/webhooks/crawl-complete",
+        include_data=True
+    )
+
+    # Example 3: LLM extraction with webhook (notification only)
+    time.sleep(5)  # Wait a bit between requests
+    print(f"\n{'='*60}")
+    print("Example 3: LLM Extraction with Webhook (Notification Only)")
+    print(f"{'='*60}")
+    task_id_3 = submit_llm_job_with_webhook(
+        url="https://www.example.com",
+        query="Extract the main heading and description from this page.",
+        webhook_url=f"{WEBHOOK_BASE_URL}/webhooks/llm-complete",
+        include_data=False,
+        provider="openai/gpt-4o-mini"
+    )
+
+    # Example 4: LLM extraction with webhook (data included + schema)
+    time.sleep(5)  # Wait a bit between requests
+    print(f"\n{'='*60}")
+    print("Example 4: LLM Extraction with Schema and Full Data")
+    print(f"{'='*60}")
+
+    # Define a schema for structured extraction
+    schema = json.dumps({
+        "type": "object",
+        "properties": {
+            "title": {"type": "string", "description": "Page title"},
+            "description": {"type": "string", "description": "Page description"}
+        },
+        "required": ["title"]
+    })
+
+    task_id_4 = submit_llm_job_with_webhook(
+        url="https://www.python.org",
+        query="Extract the title and description of this website",
+        webhook_url=f"{WEBHOOK_BASE_URL}/webhooks/llm-complete",
+        include_data=True,
+        schema=schema,
+        provider="openai/gpt-4o-mini"
+    )
+
+    # Example 5: Traditional polling (no webhook)
+    time.sleep(5)  # Wait a bit between requests
+    print(f"\n{'='*60}")
+    print("Example 5: Traditional Polling (No Webhook)")
+    print(f"{'='*60}")
+    task_id_5 = submit_job_without_webhook(
+        urls=["https://github.com"]
+    )
+    if task_id_5:
+        result = poll_job_status(task_id_5)
+        if result and result.get('status') == 'completed':
+            print(f"   ✅ Results retrieved via polling")
+
+    # Wait for webhooks to arrive
+    print(f"\n⏳ Waiting for webhooks to be received...")
+    time.sleep(30)  # Give jobs time to complete and webhooks to arrive (longer for LLM)
+
+    # Summary
+    print(f"\n{'='*60}")
+    print("Summary")
+    print(f"{'='*60}")
+    print(f"Total webhooks received: {len(received_webhooks)}")
+
+    crawl_webhooks = [w for w in received_webhooks if w['task_type'] == 'crawl']
+    llm_webhooks = [w for w in received_webhooks if w['task_type'] == 'llm_extraction']
+
+    print(f"\n📊 Breakdown:")
+    print(f"   - Crawl webhooks: {len(crawl_webhooks)}")
+    print(f"   - LLM extraction webhooks: {len(llm_webhooks)}")
+
+    print(f"\n📋 Details:")
+    for i, webhook in enumerate(received_webhooks, 1):
+        task_type = webhook['task_type']
+        icon = "🕷️" if task_type == "crawl" else "🤖"
+        print(f"{i}. {icon} Task {webhook['task_id']}: {webhook['status']} ({task_type})")
+
+    print(f"\n✅ Demo completed!")
+    print(f"\n💡 Pro tips:")
+    print(f"   - In production, your webhook URL should be publicly accessible")
+    print(f"     (e.g., https://myapp.com/webhooks) or use ngrok for testing")
+    print(f"   - Both /crawl/job and /llm/job support the same webhook configuration")
+    print(f"   - Use webhook_data_in_payload=true to get results directly in the webhook")
+    print(f"   - LLM jobs may take longer, adjust timeouts accordingly")
+
+
+if __name__ == "__main__":
+    main()

docs/md_v2/advanced/adaptive-strategies.md

@@ -126,6 +126,30 @@ Factors:
 - URL depth (fewer slashes = higher authority)
 - Clean URL structure
 
+### Custom Link Scoring
+
+```python
+class CustomLinkScorer:
+    def score(self, link: Link, query: str, state: CrawlState) -> float:
+        # Prioritize specific URL patterns
+        if "/api/reference/" in link.href:
+            return 2.0  # Double the score
+        
+        # Deprioritize certain sections
+        if "/archive/" in link.href:
+            return 0.1  # Reduce score by 90%
+        
+        # Default scoring
+        return 1.0
+
+# Use with adaptive crawler
+adaptive = AdaptiveCrawler(
+    crawler,
+    config=config,
+    link_scorer=CustomLinkScorer()
+)
+```
+
 ## Domain-Specific Configurations
 
 ### Technical Documentation
@@ -206,12 +230,8 @@ config = AdaptiveConfig(
 
 # Periodically clean state
 if len(state.knowledge_base) > 1000:
-    # Keep only the top 500 most relevant docs
-    top_content = adaptive.get_relevant_content(top_k=500)
-    keep_indices = {d["index"] for d in top_content}
-    state.knowledge_base = [
-        doc for i, doc in enumerate(state.knowledge_base) if i in keep_indices
-    ]
+    # Keep only most relevant
+    state.knowledge_base = get_top_relevant(state.knowledge_base, 500)
 ```
 
 ### Parallel Processing
@@ -232,6 +252,18 @@ tasks = [
 results = await asyncio.gather(*tasks)
 ```
 
+### Caching Strategy
+
+```python
+# Enable caching for repeated crawls
+async with AsyncWebCrawler(
+    config=BrowserConfig(
+        cache_mode=CacheMode.ENABLED
+    )
+) as crawler:
+    adaptive = AdaptiveCrawler(crawler, config)
+```
+
 ## Debugging & Analysis
 
 ### Enable Verbose Logging
@@ -290,9 +322,9 @@ with open("crawl_analysis.json", "w") as f:
 ### Implementing a Custom Strategy
 
 ```python
-from crawl4ai.adaptive_crawler import CrawlStrategy
+from crawl4ai.adaptive_crawler import BaseStrategy
 
-class DomainSpecificStrategy(CrawlStrategy):
+class DomainSpecificStrategy(BaseStrategy):
     def calculate_coverage(self, state: CrawlState) -> float:
         # Custom coverage calculation
         # e.g., weight certain terms more heavily
@@ -319,7 +351,7 @@ adaptive = AdaptiveCrawler(
 ### Combining Strategies
 
 ```python
-class HybridStrategy(CrawlStrategy):
+class HybridStrategy(BaseStrategy):
     def __init__(self):
         self.strategies = [
             TechnicalDocStrategy(),

docs/md_v2/core/docker-deployment.md

@@ -89,16 +89,6 @@ ANTHROPIC_API_KEY=your-anthropic-key
 # TOGETHER_API_KEY=your-together-key
 # MISTRAL_API_KEY=your-mistral-key
 # GEMINI_API_TOKEN=your-gemini-token
-
-# Optional: Global LLM settings
-# LLM_PROVIDER=openai/gpt-4o-mini
-# LLM_TEMPERATURE=0.7
-# LLM_BASE_URL=https://api.custom.com/v1
-
-# Optional: Provider-specific overrides
-# OPENAI_TEMPERATURE=0.5
-# OPENAI_BASE_URL=https://custom-openai.com/v1
-# ANTHROPIC_TEMPERATURE=0.3
 EOL
 ```
 > 🔑 **Note**: Keep your API keys secure! Never commit `.llm.env` to version control.
@@ -166,43 +156,27 @@ cp deploy/docker/.llm.env.example .llm.env
 
 **Flexible LLM Provider Configuration:**
 
-The Docker setup now supports flexible LLM provider configuration through a hierarchical system:
+The Docker setup now supports flexible LLM provider configuration through three methods:
 
-1. **API Request Parameters** (Highest Priority): Specify per request
+1. **Environment Variable** (Highest Priority): Set `LLM_PROVIDER` to override the default
+   ```bash
+   export LLM_PROVIDER="anthropic/claude-3-opus"
+   # Or in your .llm.env file:
+   # LLM_PROVIDER=anthropic/claude-3-opus
+   ```
+
+2. **API Request Parameter**: Specify provider per request
    ```json
    {
      "url": "https://example.com",
      "f": "llm",
-     "provider": "groq/mixtral-8x7b",
-     "temperature": 0.7,
-     "base_url": "https://api.custom.com/v1"
+     "provider": "groq/mixtral-8x7b"
    }
    ```
 
-2. **Provider-Specific Environment Variables**: Override for specific providers
-   ```bash
-   # In your .llm.env file:
-   OPENAI_TEMPERATURE=0.5
-   OPENAI_BASE_URL=https://custom-openai.com/v1
-   ANTHROPIC_TEMPERATURE=0.3
-   ```
+3. **Config File Default**: Falls back to `config.yml` (default: `openai/gpt-4o-mini`)
 
-3. **Global Environment Variables**: Set defaults for all providers
-   ```bash
-   # In your .llm.env file:
-   LLM_PROVIDER=anthropic/claude-3-opus
-   LLM_TEMPERATURE=0.7
-   LLM_BASE_URL=https://api.proxy.com/v1
-   ```
-
-4. **Config File Default**: Falls back to `config.yml` (default: `openai/gpt-4o-mini`)
-
-The system automatically selects the appropriate API key based on the provider. LiteLLM handles finding the correct environment variable for each provider (e.g., OPENAI_API_KEY for OpenAI, GEMINI_API_TOKEN for Google Gemini, etc.).
-
-**Supported LLM Parameters:**
-- `provider`: LLM provider and model (e.g., "openai/gpt-4", "anthropic/claude-3-opus")
-- `temperature`: Controls randomness (0.0-2.0, lower = more focused, higher = more creative)
-- `base_url`: Custom API endpoint for proxy servers or alternative endpoints
+The system automatically selects the appropriate API key based on the configured `api_key_env` in the config file.
 
 #### 3. Build and Run with Compose
 
@@ -581,101 +555,6 @@ Crucially, when sending configurations directly via JSON, they **must** follow t
 **LLM Extraction Strategy** *(Keep example, ensure schema uses type/value wrapper)*
 *(Keep Deep Crawler Example)*
 
-### LLM Configuration Examples
-
-The Docker API supports dynamic LLM configuration through multiple levels:
-
-#### Temperature Control
-
-Temperature affects the randomness of LLM responses (0.0 = deterministic, 2.0 = very creative):
-
-```python
-import requests
-
-# Low temperature for factual extraction
-response = requests.post(
-    "http://localhost:11235/md",
-    json={
-        "url": "https://example.com",
-        "f": "llm",
-        "q": "Extract all dates and numbers from this page",
-        "temperature": 0.2  # Very focused, deterministic
-    }
-)
-
-# High temperature for creative tasks
-response = requests.post(
-    "http://localhost:11235/md",
-    json={
-        "url": "https://example.com", 
-        "f": "llm",
-        "q": "Write a creative summary of this content",
-        "temperature": 1.2  # More creative, varied responses
-    }
-)
-```
-
-#### Custom API Endpoints
-
-Use custom base URLs for proxy servers or alternative API endpoints:
-
-```python
-
-# Using a local LLM server
-response = requests.post(
-    "http://localhost:11235/md",
-    json={
-        "url": "https://example.com",
-        "f": "llm",
-        "q": "Extract key information",
-        "provider": "ollama/llama2",
-        "base_url": "http://localhost:11434/v1"
-    }
-)
-```
-
-#### Dynamic Provider Selection
-
-Switch between providers based on task requirements:
-
-```python
-async def smart_extraction(url: str, content_type: str):
-    """Select provider and temperature based on content type"""
-    
-    configs = {
-        "technical": {
-            "provider": "openai/gpt-4",
-            "temperature": 0.3,
-            "query": "Extract technical specifications and code examples"
-        },
-        "creative": {
-            "provider": "anthropic/claude-3-opus",
-            "temperature": 0.9,
-            "query": "Create an engaging narrative summary"
-        },
-        "quick": {
-            "provider": "groq/mixtral-8x7b",
-            "temperature": 0.5,
-            "query": "Quick summary in bullet points"
-        }
-    }
-    
-    config = configs.get(content_type, configs["quick"])
-    
-    response = await httpx.post(
-        "http://localhost:11235/md",
-        json={
-            "url": url,
-            "f": "llm",
-            "q": config["query"],
-            "provider": config["provider"],
-            "temperature": config["temperature"]
-        }
-    )
-    
-    return response.json()
-```
-
 ### REST API Examples
 
 Update URLs to use port `11235`.
@@ -814,8 +693,8 @@ app:
 # Default LLM Configuration
 llm:
   provider: "openai/gpt-4o-mini"  # Can be overridden by LLM_PROVIDER env var
-  # api_key: sk-...  # If you pass the API key directly (not recommended)
-  # temperature and base_url are controlled via environment variables or request parameters
+  api_key_env: "OPENAI_API_KEY"
+  # api_key: sk-...  # If you pass the API key directly then api_key_env will be ignored
 
 # Redis Configuration (Used by internal Redis server managed by supervisord)
 redis:

docs/md_v2/core/quickstart.md

@@ -79,7 +79,7 @@ if __name__ == "__main__":
     asyncio.run(main())
 ```
 
-> IMPORTANT: By default cache mode is set to `CacheMode.BYPASS` to have fresh content. Set `CacheMode.ENABLED` to enable caching.
+> IMPORTANT: By default cache mode is set to `CacheMode.ENABLED`. So to have fresh content, you need to set it to `CacheMode.BYPASS`
 
 We’ll explore more advanced config in later tutorials (like enabling proxies, PDF output, multi-tab sessions, etc.). For now, just note how you pass these objects to manage crawling.
 

docs/md_v2/core/url-seeding.md

@@ -102,16 +102,16 @@ async def smart_blog_crawler():
     
     # Step 2: Configure discovery - let's find all blog posts
     config = SeedingConfig(
-        source="sitemap+cc",      # Use the website's sitemap+cc
-        pattern="*/courses/*",    # Only courses related posts
+        source="sitemap",           # Use the website's sitemap
+        pattern="*/blog/*.html",    # Only blog posts
         extract_head=True,          # Get page metadata
         max_urls=100               # Limit for this example
     )
     
     # Step 3: Discover URLs from the Python blog
-    print("🔍 Discovering course posts...")
+    print("🔍 Discovering blog posts...")
     urls = await seeder.urls("realpython.com", config)
-    print(f"✅ Found {len(urls)} course posts")
+    print(f"✅ Found {len(urls)} blog posts")
     
     # Step 4: Filter for Python tutorials (using metadata!)
     tutorials = [
@@ -134,8 +134,7 @@ async def smart_blog_crawler():
     async with AsyncWebCrawler() as crawler:
         config = CrawlerRunConfig(
             only_text=True,
-            word_count_threshold=300,  # Only substantial articles
-            stream=True
+            word_count_threshold=300  # Only substantial articles
         )
         
         # Extract URLs and crawl them
@@ -156,7 +155,7 @@ asyncio.run(smart_blog_crawler())
 
 **What just happened?**
 
-1. We discovered all blog URLs from the sitemap+cc
+1. We discovered all blog URLs from the sitemap
 2. We filtered using metadata (no crawling needed!)
 3. We crawled only the relevant tutorials
 4. We saved tons of time and bandwidth
@@ -283,8 +282,8 @@ config = SeedingConfig(
     live_check=True,  # Verify each URL is accessible
     concurrency=20    # Check 20 URLs in parallel
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("example.com", config)
+
+urls = await seeder.urls("example.com", config)
 
 # Now you can filter by status
 live_urls = [u for u in urls if u["status"] == "valid"]
@@ -312,8 +311,8 @@ This is where URL seeding gets really powerful. Instead of crawling entire pages
 config = SeedingConfig(
     extract_head=True  # Extract metadata from <head> section
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("example.com", config)
+
+urls = await seeder.urls("example.com", config)
 
 # Now each URL has rich metadata
 for url in urls[:3]:
@@ -388,8 +387,8 @@ config = SeedingConfig(
     scoring_method="bm25",
     score_threshold=0.3
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("example.com", config)
+
+urls = await seeder.urls("example.com", config)
 
 # URLs are scored based on:
 # 1. Domain parts matching (e.g., 'python' in python.example.com)
@@ -430,8 +429,8 @@ config = SeedingConfig(
     extract_head=True,
     live_check=True
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("blog.example.com", config)
+
+urls = await seeder.urls("blog.example.com", config)
 
 # Analyze the results
 for url in urls[:5]:
@@ -489,8 +488,8 @@ config = SeedingConfig(
     scoring_method="bm25",       # Use BM25 algorithm
     score_threshold=0.3          # Minimum relevance score
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("realpython.com", config)
+
+urls = await seeder.urls("realpython.com", config)
 
 # Results are automatically sorted by relevance!
 for url in urls[:5]:
@@ -512,8 +511,8 @@ config = SeedingConfig(
     score_threshold=0.5,
     max_urls=20
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("docs.example.com", config)
+
+urls = await seeder.urls("docs.example.com", config)
 
 # The highest scoring URLs will be API docs!
 ```
@@ -530,8 +529,8 @@ config = SeedingConfig(
     score_threshold=0.4,
     pattern="*/product/*"  # Combine with pattern matching
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("shop.example.com", config)
+
+urls = await seeder.urls("shop.example.com", config)
 
 # Filter further by price (from metadata)
 affordable = [
@@ -551,8 +550,8 @@ config = SeedingConfig(
     scoring_method="bm25",
     score_threshold=0.35
 )
-async with AsyncUrlSeeder() as seeder:
-    urls = await seeder.urls("technews.com", config)
+
+urls = await seeder.urls("technews.com", config)
 
 # Filter by date
 from datetime import datetime, timedelta
@@ -592,8 +591,8 @@ for query in queries:
         score_threshold=0.4,
         max_urls=10  # Top 10 per topic
     )
-    async with AsyncUrlSeeder() as seeder:
-        urls = await seeder.urls("learning-platform.com", config)
+    
+    urls = await seeder.urls("learning-platform.com", config)
     all_tutorials.extend(urls)
 
 # Remove duplicates while preserving order
@@ -626,8 +625,7 @@ config = SeedingConfig(
 )
 
 # Returns a dictionary: {domain: [urls]}
-async with AsyncUrlSeeder() as seeder:
-    results = await seeder.many_urls(domains, config)
+results = await seeder.many_urls(domains, config)
 
 # Process results
 for domain, urls in results.items():
@@ -656,8 +654,8 @@ config = SeedingConfig(
     pattern="*/blog/*",
     max_urls=100
 )
-async with AsyncUrlSeeder() as seeder:
-    results = await seeder.many_urls(competitors, config)
+
+results = await seeder.many_urls(competitors, config)
 
 # Analyze content types
 for domain, urls in results.items():
@@ -692,8 +690,8 @@ config = SeedingConfig(
     score_threshold=0.3,
     max_urls=20  # Per site
 )
-async with AsyncUrlSeeder() as seeder:
-    results = await seeder.many_urls(educational_sites, config)
+
+results = await seeder.many_urls(educational_sites, config)
 
 # Find the best beginner tutorials
 all_tutorials = []
@@ -733,8 +731,8 @@ config = SeedingConfig(
     score_threshold=0.5,  # High threshold for relevance
     max_urls=10
 )
-async with AsyncUrlSeeder() as seeder:
-    results = await seeder.many_urls(news_sites, config)
+
+results = await seeder.many_urls(news_sites, config)
 
 # Collect all mentions
 mentions = []

test_llm_webhook_feature.py

@@ -0,0 +1,401 @@
+#!/usr/bin/env python3
+"""
+Test script to validate webhook implementation for /llm/job endpoint.
+
+This tests that the /llm/job endpoint now supports webhooks
+following the same pattern as /crawl/job.
+"""
+
+import sys
+import os
+
+# Add deploy/docker to path
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'deploy', 'docker'))
+
+def test_llm_job_payload_model():
+    """Test that LlmJobPayload includes webhook_config field"""
+    print("=" * 60)
+    print("TEST 1: LlmJobPayload Model")
+    print("=" * 60)
+
+    try:
+        from job import LlmJobPayload
+        from schemas import WebhookConfig
+        from pydantic import ValidationError
+
+        # Test with webhook_config
+        payload_dict = {
+            "url": "https://example.com",
+            "q": "Extract main content",
+            "schema": None,
+            "cache": False,
+            "provider": None,
+            "webhook_config": {
+                "webhook_url": "https://myapp.com/webhook",
+                "webhook_data_in_payload": True,
+                "webhook_headers": {"X-Secret": "token"}
+            }
+        }
+
+        payload = LlmJobPayload(**payload_dict)
+
+        print(f"✅ LlmJobPayload accepts webhook_config")
+        print(f"   - URL: {payload.url}")
+        print(f"   - Query: {payload.q}")
+        print(f"   - Webhook URL: {payload.webhook_config.webhook_url}")
+        print(f"   - Data in payload: {payload.webhook_config.webhook_data_in_payload}")
+
+        # Test without webhook_config (should be optional)
+        minimal_payload = {
+            "url": "https://example.com",
+            "q": "Extract content"
+        }
+
+        payload2 = LlmJobPayload(**minimal_payload)
+        assert payload2.webhook_config is None, "webhook_config should be optional"
+        print(f"✅ LlmJobPayload works without webhook_config (optional)")
+
+        return True
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_handle_llm_request_signature():
+    """Test that handle_llm_request accepts webhook_config parameter"""
+    print("\n" + "=" * 60)
+    print("TEST 2: handle_llm_request Function Signature")
+    print("=" * 60)
+
+    try:
+        from api import handle_llm_request
+        import inspect
+
+        sig = inspect.signature(handle_llm_request)
+        params = list(sig.parameters.keys())
+
+        print(f"Function parameters: {params}")
+
+        if 'webhook_config' in params:
+            print(f"✅ handle_llm_request has webhook_config parameter")
+
+            # Check that it's optional with default None
+            webhook_param = sig.parameters['webhook_config']
+            if webhook_param.default is None or webhook_param.default == inspect.Parameter.empty:
+                print(f"✅ webhook_config is optional (default: {webhook_param.default})")
+            else:
+                print(f"⚠️  webhook_config default is: {webhook_param.default}")
+
+            return True
+        else:
+            print(f"❌ handle_llm_request missing webhook_config parameter")
+            return False
+
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_process_llm_extraction_signature():
+    """Test that process_llm_extraction accepts webhook_config parameter"""
+    print("\n" + "=" * 60)
+    print("TEST 3: process_llm_extraction Function Signature")
+    print("=" * 60)
+
+    try:
+        from api import process_llm_extraction
+        import inspect
+
+        sig = inspect.signature(process_llm_extraction)
+        params = list(sig.parameters.keys())
+
+        print(f"Function parameters: {params}")
+
+        if 'webhook_config' in params:
+            print(f"✅ process_llm_extraction has webhook_config parameter")
+
+            webhook_param = sig.parameters['webhook_config']
+            if webhook_param.default is None or webhook_param.default == inspect.Parameter.empty:
+                print(f"✅ webhook_config is optional (default: {webhook_param.default})")
+            else:
+                print(f"⚠️  webhook_config default is: {webhook_param.default}")
+
+            return True
+        else:
+            print(f"❌ process_llm_extraction missing webhook_config parameter")
+            return False
+
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_webhook_integration_in_api():
+    """Test that api.py properly integrates webhook notifications"""
+    print("\n" + "=" * 60)
+    print("TEST 4: Webhook Integration in process_llm_extraction")
+    print("=" * 60)
+
+    try:
+        api_file = os.path.join(os.path.dirname(__file__), 'deploy', 'docker', 'api.py')
+
+        with open(api_file, 'r') as f:
+            api_content = f.read()
+
+        # Check for WebhookDeliveryService initialization
+        if 'webhook_service = WebhookDeliveryService(config)' in api_content:
+            print("✅ process_llm_extraction initializes WebhookDeliveryService")
+        else:
+            print("❌ Missing WebhookDeliveryService initialization in process_llm_extraction")
+            return False
+
+        # Check for notify_job_completion calls with llm_extraction
+        if 'task_type="llm_extraction"' in api_content:
+            print("✅ Uses correct task_type='llm_extraction' for notifications")
+        else:
+            print("❌ Missing task_type='llm_extraction' in webhook notifications")
+            return False
+
+        # Count webhook notification calls (should have at least 3: success + 2 failure paths)
+        notification_count = api_content.count('await webhook_service.notify_job_completion')
+        # Find only in process_llm_extraction function
+        llm_func_start = api_content.find('async def process_llm_extraction')
+        llm_func_end = api_content.find('\nasync def ', llm_func_start + 1)
+        if llm_func_end == -1:
+            llm_func_end = len(api_content)
+
+        llm_func_content = api_content[llm_func_start:llm_func_end]
+        llm_notification_count = llm_func_content.count('await webhook_service.notify_job_completion')
+
+        print(f"✅ Found {llm_notification_count} webhook notification calls in process_llm_extraction")
+
+        if llm_notification_count >= 3:
+            print(f"✅ Sufficient notification points (success + failure paths)")
+        else:
+            print(f"⚠️  Expected at least 3 notification calls, found {llm_notification_count}")
+
+        return True
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_job_endpoint_integration():
+    """Test that /llm/job endpoint extracts and passes webhook_config"""
+    print("\n" + "=" * 60)
+    print("TEST 5: /llm/job Endpoint Integration")
+    print("=" * 60)
+
+    try:
+        job_file = os.path.join(os.path.dirname(__file__), 'deploy', 'docker', 'job.py')
+
+        with open(job_file, 'r') as f:
+            job_content = f.read()
+
+        # Find the llm_job_enqueue function
+        llm_job_start = job_content.find('async def llm_job_enqueue')
+        llm_job_end = job_content.find('\n\n@router', llm_job_start + 1)
+        if llm_job_end == -1:
+            llm_job_end = job_content.find('\n\nasync def', llm_job_start + 1)
+
+        llm_job_func = job_content[llm_job_start:llm_job_end]
+
+        # Check for webhook_config extraction
+        if 'webhook_config = None' in llm_job_func:
+            print("✅ llm_job_enqueue initializes webhook_config variable")
+        else:
+            print("❌ Missing webhook_config initialization")
+            return False
+
+        if 'if payload.webhook_config:' in llm_job_func:
+            print("✅ llm_job_enqueue checks for payload.webhook_config")
+        else:
+            print("❌ Missing webhook_config check")
+            return False
+
+        if 'webhook_config = payload.webhook_config.model_dump(mode=\'json\')' in llm_job_func:
+            print("✅ llm_job_enqueue converts webhook_config to dict")
+        else:
+            print("❌ Missing webhook_config.model_dump conversion")
+            return False
+
+        if 'webhook_config=webhook_config' in llm_job_func:
+            print("✅ llm_job_enqueue passes webhook_config to handle_llm_request")
+        else:
+            print("❌ Missing webhook_config parameter in handle_llm_request call")
+            return False
+
+        return True
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_create_new_task_integration():
+    """Test that create_new_task stores webhook_config in Redis"""
+    print("\n" + "=" * 60)
+    print("TEST 6: create_new_task Webhook Storage")
+    print("=" * 60)
+
+    try:
+        api_file = os.path.join(os.path.dirname(__file__), 'deploy', 'docker', 'api.py')
+
+        with open(api_file, 'r') as f:
+            api_content = f.read()
+
+        # Find create_new_task function
+        create_task_start = api_content.find('async def create_new_task')
+        create_task_end = api_content.find('\nasync def ', create_task_start + 1)
+        if create_task_end == -1:
+            create_task_end = len(api_content)
+
+        create_task_func = api_content[create_task_start:create_task_end]
+
+        # Check for webhook_config storage
+        if 'if webhook_config:' in create_task_func:
+            print("✅ create_new_task checks for webhook_config")
+        else:
+            print("❌ Missing webhook_config check in create_new_task")
+            return False
+
+        if 'task_data["webhook_config"] = json.dumps(webhook_config)' in create_task_func:
+            print("✅ create_new_task stores webhook_config in Redis task data")
+        else:
+            print("❌ Missing webhook_config storage in task_data")
+            return False
+
+        # Check that webhook_config is passed to process_llm_extraction
+        if 'webhook_config' in create_task_func and 'background_tasks.add_task' in create_task_func:
+            print("✅ create_new_task passes webhook_config to background task")
+        else:
+            print("⚠️  Could not verify webhook_config passed to background task")
+
+        return True
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_pattern_consistency():
+    """Test that /llm/job follows the same pattern as /crawl/job"""
+    print("\n" + "=" * 60)
+    print("TEST 7: Pattern Consistency with /crawl/job")
+    print("=" * 60)
+
+    try:
+        api_file = os.path.join(os.path.dirname(__file__), 'deploy', 'docker', 'api.py')
+
+        with open(api_file, 'r') as f:
+            api_content = f.read()
+
+        # Find handle_crawl_job to compare pattern
+        crawl_job_start = api_content.find('async def handle_crawl_job')
+        crawl_job_end = api_content.find('\nasync def ', crawl_job_start + 1)
+        if crawl_job_end == -1:
+            crawl_job_end = len(api_content)
+        crawl_job_func = api_content[crawl_job_start:crawl_job_end]
+
+        # Find process_llm_extraction
+        llm_extract_start = api_content.find('async def process_llm_extraction')
+        llm_extract_end = api_content.find('\nasync def ', llm_extract_start + 1)
+        if llm_extract_end == -1:
+            llm_extract_end = len(api_content)
+        llm_extract_func = api_content[llm_extract_start:llm_extract_end]
+
+        print("Checking pattern consistency...")
+
+        # Both should initialize WebhookDeliveryService
+        crawl_has_service = 'webhook_service = WebhookDeliveryService(config)' in crawl_job_func
+        llm_has_service = 'webhook_service = WebhookDeliveryService(config)' in llm_extract_func
+
+        if crawl_has_service and llm_has_service:
+            print("✅ Both initialize WebhookDeliveryService")
+        else:
+            print(f"❌ Service initialization mismatch (crawl: {crawl_has_service}, llm: {llm_has_service})")
+            return False
+
+        # Both should call notify_job_completion on success
+        crawl_notifies_success = 'status="completed"' in crawl_job_func and 'notify_job_completion' in crawl_job_func
+        llm_notifies_success = 'status="completed"' in llm_extract_func and 'notify_job_completion' in llm_extract_func
+
+        if crawl_notifies_success and llm_notifies_success:
+            print("✅ Both notify on success")
+        else:
+            print(f"❌ Success notification mismatch (crawl: {crawl_notifies_success}, llm: {llm_notifies_success})")
+            return False
+
+        # Both should call notify_job_completion on failure
+        crawl_notifies_failure = 'status="failed"' in crawl_job_func and 'error=' in crawl_job_func
+        llm_notifies_failure = 'status="failed"' in llm_extract_func and 'error=' in llm_extract_func
+
+        if crawl_notifies_failure and llm_notifies_failure:
+            print("✅ Both notify on failure")
+        else:
+            print(f"❌ Failure notification mismatch (crawl: {crawl_notifies_failure}, llm: {llm_notifies_failure})")
+            return False
+
+        print("✅ /llm/job follows the same pattern as /crawl/job")
+        return True
+
+    except Exception as e:
+        print(f"❌ Failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def main():
+    """Run all tests"""
+    print("\n🧪 LLM Job Webhook Feature Validation")
+    print("=" * 60)
+    print("Testing that /llm/job now supports webhooks like /crawl/job")
+    print("=" * 60 + "\n")
+
+    results = []
+
+    # Run all tests
+    results.append(("LlmJobPayload Model", test_llm_job_payload_model()))
+    results.append(("handle_llm_request Signature", test_handle_llm_request_signature()))
+    results.append(("process_llm_extraction Signature", test_process_llm_extraction_signature()))
+    results.append(("Webhook Integration", test_webhook_integration_in_api()))
+    results.append(("/llm/job Endpoint", test_job_endpoint_integration()))
+    results.append(("create_new_task Storage", test_create_new_task_integration()))
+    results.append(("Pattern Consistency", test_pattern_consistency()))
+
+    # Print summary
+    print("\n" + "=" * 60)
+    print("TEST SUMMARY")
+    print("=" * 60)
+
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+
+    for test_name, result in results:
+        status = "✅ PASS" if result else "❌ FAIL"
+        print(f"{status} - {test_name}")
+
+    print(f"\n{'=' * 60}")
+    print(f"Results: {passed}/{total} tests passed")
+    print(f"{'=' * 60}")
+
+    if passed == total:
+        print("\n🎉 All tests passed! /llm/job webhook feature is correctly implemented.")
+        print("\n📝 Summary of changes:")
+        print("  1. LlmJobPayload model includes webhook_config field")
+        print("  2. /llm/job endpoint extracts and passes webhook_config")
+        print("  3. handle_llm_request accepts webhook_config parameter")
+        print("  4. create_new_task stores webhook_config in Redis")
+        print("  5. process_llm_extraction sends webhook notifications")
+        print("  6. Follows the same pattern as /crawl/job")
+        return 0
+    else:
+        print(f"\n⚠️  {total - passed} test(s) failed. Please review the output above.")
+        return 1
+
+if __name__ == "__main__":
+    exit(main())

test_webhook_implementation.py

@@ -0,0 +1,307 @@
+"""
+Simple test script to validate webhook implementation without running full server.
+
+This script tests:
+1. Webhook module imports and syntax
+2. WebhookDeliveryService initialization
+3. Payload construction logic
+4. Configuration parsing
+"""
+
+import sys
+import os
+import json
+from datetime import datetime, timezone
+
+# Add deploy/docker to path to import modules
+# sys.path.insert(0, '/home/user/crawl4ai/deploy/docker')
+sys.path.insert(0, os.path.join(os.path.dirname(__file__), 'deploy', 'docker'))
+
+def test_imports():
+    """Test that all webhook-related modules can be imported"""
+    print("=" * 60)
+    print("TEST 1: Module Imports")
+    print("=" * 60)
+
+    try:
+        from webhook import WebhookDeliveryService
+        print("✅ webhook.WebhookDeliveryService imported successfully")
+    except Exception as e:
+        print(f"❌ Failed to import webhook module: {e}")
+        return False
+
+    try:
+        from schemas import WebhookConfig, WebhookPayload
+        print("✅ schemas.WebhookConfig imported successfully")
+        print("✅ schemas.WebhookPayload imported successfully")
+    except Exception as e:
+        print(f"❌ Failed to import schemas: {e}")
+        return False
+
+    return True
+
+def test_webhook_service_init():
+    """Test WebhookDeliveryService initialization"""
+    print("\n" + "=" * 60)
+    print("TEST 2: WebhookDeliveryService Initialization")
+    print("=" * 60)
+
+    try:
+        from webhook import WebhookDeliveryService
+
+        # Test with default config
+        config = {
+            "webhooks": {
+                "enabled": True,
+                "default_url": None,
+                "data_in_payload": False,
+                "retry": {
+                    "max_attempts": 5,
+                    "initial_delay_ms": 1000,
+                    "max_delay_ms": 32000,
+                    "timeout_ms": 30000
+                },
+                "headers": {
+                    "User-Agent": "Crawl4AI-Webhook/1.0"
+                }
+            }
+        }
+
+        service = WebhookDeliveryService(config)
+
+        print(f"✅ Service initialized successfully")
+        print(f"   - Max attempts: {service.max_attempts}")
+        print(f"   - Initial delay: {service.initial_delay}s")
+        print(f"   - Max delay: {service.max_delay}s")
+        print(f"   - Timeout: {service.timeout}s")
+
+        # Verify calculations
+        assert service.max_attempts == 5, "Max attempts should be 5"
+        assert service.initial_delay == 1.0, "Initial delay should be 1.0s"
+        assert service.max_delay == 32.0, "Max delay should be 32.0s"
+        assert service.timeout == 30.0, "Timeout should be 30.0s"
+
+        print("✅ All configuration values correct")
+
+        return True
+    except Exception as e:
+        print(f"❌ Service initialization failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_webhook_config_model():
+    """Test WebhookConfig Pydantic model"""
+    print("\n" + "=" * 60)
+    print("TEST 3: WebhookConfig Model Validation")
+    print("=" * 60)
+
+    try:
+        from schemas import WebhookConfig
+        from pydantic import ValidationError
+
+        # Test valid config
+        valid_config = {
+            "webhook_url": "https://example.com/webhook",
+            "webhook_data_in_payload": True,
+            "webhook_headers": {"X-Secret": "token123"}
+        }
+
+        config = WebhookConfig(**valid_config)
+        print(f"✅ Valid config accepted:")
+        print(f"   - URL: {config.webhook_url}")
+        print(f"   - Data in payload: {config.webhook_data_in_payload}")
+        print(f"   - Headers: {config.webhook_headers}")
+
+        # Test minimal config
+        minimal_config = {
+            "webhook_url": "https://example.com/webhook"
+        }
+
+        config2 = WebhookConfig(**minimal_config)
+        print(f"✅ Minimal config accepted (defaults applied):")
+        print(f"   - URL: {config2.webhook_url}")
+        print(f"   - Data in payload: {config2.webhook_data_in_payload}")
+        print(f"   - Headers: {config2.webhook_headers}")
+
+        # Test invalid URL
+        try:
+            invalid_config = {
+                "webhook_url": "not-a-url"
+            }
+            config3 = WebhookConfig(**invalid_config)
+            print(f"❌ Invalid URL should have been rejected")
+            return False
+        except ValidationError as e:
+            print(f"✅ Invalid URL correctly rejected")
+
+        return True
+    except Exception as e:
+        print(f"❌ Model validation test failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_payload_construction():
+    """Test webhook payload construction logic"""
+    print("\n" + "=" * 60)
+    print("TEST 4: Payload Construction")
+    print("=" * 60)
+
+    try:
+        # Simulate payload construction from notify_job_completion
+        task_id = "crawl_abc123"
+        task_type = "crawl"
+        status = "completed"
+        urls = ["https://example.com"]
+
+        payload = {
+            "task_id": task_id,
+            "task_type": task_type,
+            "status": status,
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "urls": urls
+        }
+
+        print(f"✅ Basic payload constructed:")
+        print(json.dumps(payload, indent=2))
+
+        # Test with error
+        error_payload = {
+            "task_id": "crawl_xyz789",
+            "task_type": "crawl",
+            "status": "failed",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "urls": ["https://example.com"],
+            "error": "Connection timeout"
+        }
+
+        print(f"\n✅ Error payload constructed:")
+        print(json.dumps(error_payload, indent=2))
+
+        # Test with data
+        data_payload = {
+            "task_id": "crawl_def456",
+            "task_type": "crawl",
+            "status": "completed",
+            "timestamp": datetime.now(timezone.utc).isoformat(),
+            "urls": ["https://example.com"],
+            "data": {
+                "results": [
+                    {"url": "https://example.com", "markdown": "# Example"}
+                ]
+            }
+        }
+
+        print(f"\n✅ Data payload constructed:")
+        print(json.dumps(data_payload, indent=2))
+
+        return True
+    except Exception as e:
+        print(f"❌ Payload construction failed: {e}")
+        import traceback
+        traceback.print_exc()
+        return False
+
+def test_exponential_backoff():
+    """Test exponential backoff calculation"""
+    print("\n" + "=" * 60)
+    print("TEST 5: Exponential Backoff Calculation")
+    print("=" * 60)
+
+    try:
+        initial_delay = 1.0  # 1 second
+        max_delay = 32.0     # 32 seconds
+
+        print("Backoff delays for 5 attempts:")
+        for attempt in range(5):
+            delay = min(initial_delay * (2 ** attempt), max_delay)
+            print(f"  Attempt {attempt + 1}: {delay}s")
+
+        # Verify the sequence: 1s, 2s, 4s, 8s, 16s
+        expected = [1.0, 2.0, 4.0, 8.0, 16.0]
+        actual = [min(initial_delay * (2 ** i), max_delay) for i in range(5)]
+
+        assert actual == expected, f"Expected {expected}, got {actual}"
+        print("✅ Exponential backoff sequence correct")
+
+        return True
+    except Exception as e:
+        print(f"❌ Backoff calculation failed: {e}")
+        return False
+
+def test_api_integration():
+    """Test that api.py imports webhook module correctly"""
+    print("\n" + "=" * 60)
+    print("TEST 6: API Integration")
+    print("=" * 60)
+
+    try:
+        # Check if api.py can import webhook module
+        api_path = os.path.join(os.path.dirname(__file__), 'deploy', 'docker', 'api.py')
+        with open(api_path, 'r') as f:
+            api_content = f.read()
+
+        if 'from webhook import WebhookDeliveryService' in api_content:
+            print("✅ api.py imports WebhookDeliveryService")
+        else:
+            print("❌ api.py missing webhook import")
+            return False
+
+        if 'WebhookDeliveryService(config)' in api_content:
+            print("✅ api.py initializes WebhookDeliveryService")
+        else:
+            print("❌ api.py doesn't initialize WebhookDeliveryService")
+            return False
+
+        if 'notify_job_completion' in api_content:
+            print("✅ api.py calls notify_job_completion")
+        else:
+            print("❌ api.py doesn't call notify_job_completion")
+            return False
+
+        return True
+    except Exception as e:
+        print(f"❌ API integration check failed: {e}")
+        return False
+
+def main():
+    """Run all tests"""
+    print("\n🧪 Webhook Implementation Validation Tests")
+    print("=" * 60)
+
+    results = []
+
+    # Run tests
+    results.append(("Module Imports", test_imports()))
+    results.append(("Service Initialization", test_webhook_service_init()))
+    results.append(("Config Model", test_webhook_config_model()))
+    results.append(("Payload Construction", test_payload_construction()))
+    results.append(("Exponential Backoff", test_exponential_backoff()))
+    results.append(("API Integration", test_api_integration()))
+
+    # Print summary
+    print("\n" + "=" * 60)
+    print("TEST SUMMARY")
+    print("=" * 60)
+
+    passed = sum(1 for _, result in results if result)
+    total = len(results)
+
+    for test_name, result in results:
+        status = "✅ PASS" if result else "❌ FAIL"
+        print(f"{status} - {test_name}")
+
+    print(f"\n{'=' * 60}")
+    print(f"Results: {passed}/{total} tests passed")
+    print(f"{'=' * 60}")
+
+    if passed == total:
+        print("\n🎉 All tests passed! Webhook implementation is valid.")
+        return 0
+    else:
+        print(f"\n⚠️  {total - passed} test(s) failed. Please review the output above.")
+        return 1
+
+if __name__ == "__main__":
+    exit(main())

tests/WEBHOOK_TEST_README.md

@@ -0,0 +1,251 @@
+# Webhook Feature Test Script
+
+This directory contains a comprehensive test script for the webhook feature implementation.
+
+## Overview
+
+The `test_webhook_feature.sh` script automates the entire process of testing the webhook feature:
+
+1. ✅ Fetches and switches to the webhook feature branch
+2. ✅ Activates the virtual environment
+3. ✅ Installs all required dependencies
+4. ✅ Starts Redis server in background
+5. ✅ Starts Crawl4AI server in background
+6. ✅ Runs webhook integration test
+7. ✅ Verifies job completion via webhook
+8. ✅ Cleans up and returns to original branch
+
+## Prerequisites
+
+- Python 3.10+
+- Virtual environment already created (`venv/` in project root)
+- Git repository with the webhook feature branch
+- `redis-server` (script will attempt to install if missing)
+- `curl` and `lsof` commands available
+
+## Usage
+
+### Quick Start
+
+From the project root:
+
+```bash
+./tests/test_webhook_feature.sh
+```
+
+Or from the tests directory:
+
+```bash
+cd tests
+./test_webhook_feature.sh
+```
+
+### What the Script Does
+
+#### Step 1: Branch Management
+- Saves your current branch
+- Fetches the webhook feature branch from remote
+- Switches to the webhook feature branch
+
+#### Step 2: Environment Setup
+- Activates your existing virtual environment
+- Installs dependencies from `deploy/docker/requirements.txt`
+- Installs Flask for the webhook receiver
+
+#### Step 3: Service Startup
+- Starts Redis server on port 6379
+- Starts Crawl4AI server on port 11235
+- Waits for server health check to pass
+
+#### Step 4: Webhook Test
+- Creates a webhook receiver on port 8080
+- Submits a crawl job for `https://example.com` with webhook config
+- Waits for webhook notification (60s timeout)
+- Verifies webhook payload contains expected data
+
+#### Step 5: Cleanup
+- Stops webhook receiver
+- Stops Crawl4AI server
+- Stops Redis server
+- Returns to your original branch
+
+## Expected Output
+
+```
+[INFO] Starting webhook feature test script
+[INFO] Project root: /path/to/crawl4ai
+[INFO] Step 1: Fetching PR branch...
+[INFO] Current branch: develop
+[SUCCESS] Branch fetched
+[INFO] Step 2: Switching to branch: claude/implement-webhook-crawl-feature-011CULZY1Jy8N5MUkZqXkRVp
+[SUCCESS] Switched to webhook feature branch
+[INFO] Step 3: Activating virtual environment...
+[SUCCESS] Virtual environment activated
+[INFO] Step 4: Installing server dependencies...
+[SUCCESS] Dependencies installed
+[INFO] Step 5a: Starting Redis...
+[SUCCESS] Redis started (PID: 12345)
+[INFO] Step 5b: Starting server on port 11235...
+[INFO] Server started (PID: 12346)
+[INFO] Waiting for server to be ready...
+[SUCCESS] Server is ready!
+[INFO] Step 6: Creating webhook test script...
+[INFO] Running webhook test...
+
+🚀 Submitting crawl job with webhook...
+✅ Job submitted successfully, task_id: crawl_abc123
+⏳ Waiting for webhook notification...
+
+✅ Webhook received: {
+  "task_id": "crawl_abc123",
+  "task_type": "crawl",
+  "status": "completed",
+  "timestamp": "2025-10-22T00:00:00.000000+00:00",
+  "urls": ["https://example.com"],
+  "data": { ... }
+}
+
+✅ Webhook received!
+   Task ID: crawl_abc123
+   Status: completed
+   URLs: ['https://example.com']
+   ✅ Data included in webhook payload
+   📄 Crawled 1 URL(s)
+      - https://example.com: 1234 chars
+
+🎉 Webhook test PASSED!
+
+[INFO] Step 7: Verifying test results...
+[SUCCESS] ✅ Webhook test PASSED!
+[SUCCESS] All tests completed successfully! 🎉
+[INFO] Cleanup will happen automatically...
+[INFO] Starting cleanup...
+[INFO] Stopping webhook receiver...
+[INFO] Stopping server...
+[INFO] Stopping Redis...
+[INFO] Switching back to branch: develop
+[SUCCESS] Cleanup complete
+```
+
+## Troubleshooting
+
+### Server Failed to Start
+
+If the server fails to start, check the logs:
+
+```bash
+tail -100 /tmp/crawl4ai_server.log
+```
+
+Common issues:
+- Port 11235 already in use: `lsof -ti:11235 | xargs kill -9`
+- Missing dependencies: Check that all packages are installed
+
+### Redis Connection Failed
+
+Check if Redis is running:
+
+```bash
+redis-cli ping
+# Should return: PONG
+```
+
+If not running:
+
+```bash
+redis-server --port 6379 --daemonize yes
+```
+
+### Webhook Not Received
+
+The script has a 60-second timeout for webhook delivery. If the webhook isn't received:
+
+1. Check server logs: `/tmp/crawl4ai_server.log`
+2. Verify webhook receiver is running on port 8080
+3. Check network connectivity between components
+
+### Script Interruption
+
+If the script is interrupted (Ctrl+C), cleanup happens automatically via trap. The script will:
+- Kill all background processes
+- Stop Redis
+- Return to your original branch
+
+To manually cleanup if needed:
+
+```bash
+# Kill processes by port
+lsof -ti:11235 | xargs kill -9  # Server
+lsof -ti:8080 | xargs kill -9   # Webhook receiver
+lsof -ti:6379 | xargs kill -9   # Redis
+
+# Return to your branch
+git checkout develop  # or your branch name
+```
+
+## Testing Different URLs
+
+To test with a different URL, modify the script or create a custom test:
+
+```python
+payload = {
+    "urls": ["https://your-url-here.com"],
+    "browser_config": {"headless": True},
+    "crawler_config": {"cache_mode": "bypass"},
+    "webhook_config": {
+        "webhook_url": "http://localhost:8080/webhook",
+        "webhook_data_in_payload": True
+    }
+}
+```
+
+## Files Generated
+
+The script creates temporary files:
+
+- `/tmp/crawl4ai_server.log` - Server output logs
+- `/tmp/test_webhook.py` - Webhook test Python script
+
+These are not cleaned up automatically so you can review them after the test.
+
+## Exit Codes
+
+- `0` - All tests passed successfully
+- `1` - Test failed (check output for details)
+
+## Safety Features
+
+- ✅ Automatic cleanup on exit, interrupt, or error
+- ✅ Returns to original branch on completion
+- ✅ Kills all background processes
+- ✅ Comprehensive error handling
+- ✅ Colored output for easy reading
+- ✅ Detailed logging at each step
+
+## Notes
+
+- The script uses `set -e` to exit on any command failure
+- All background processes are tracked and cleaned up
+- The virtual environment must exist before running
+- Redis must be available (installed or installable via apt-get/brew)
+
+## Integration with CI/CD
+
+This script can be integrated into CI/CD pipelines:
+
+```yaml
+# Example GitHub Actions
+- name: Test Webhook Feature
+  run: |
+    chmod +x tests/test_webhook_feature.sh
+    ./tests/test_webhook_feature.sh
+```
+
+## Support
+
+If you encounter issues:
+
+1. Check the troubleshooting section above
+2. Review server logs at `/tmp/crawl4ai_server.log`
+3. Ensure all prerequisites are met
+4. Open an issue with the full output of the script

tests/docker/test_filter_deep_crawl.py

@@ -1,201 +0,0 @@
-"""
-Test the complete fix for both the filter serialization and JSON serialization issues.
-"""
-
-import asyncio
-import httpx
-
-from crawl4ai import BrowserConfig, CacheMode, CrawlerRunConfig
-from crawl4ai.deep_crawling import BFSDeepCrawlStrategy, FilterChain, URLPatternFilter
-
-BASE_URL = "http://localhost:11234/"  # Adjust port as needed
-
-async def test_with_docker_client():
-    """Test using the Docker client (same as 1419.py)."""
-    from crawl4ai.docker_client import Crawl4aiDockerClient
-    
-    print("=" * 60)
-    print("Testing with Docker Client")
-    print("=" * 60)
-    
-    try:
-        async with Crawl4aiDockerClient(
-            base_url=BASE_URL,
-            verbose=True,
-        ) as client:
-            
-            # Create filter chain - testing the serialization fix
-            filter_chain = [
-                URLPatternFilter(
-                    # patterns=["*about*", "*privacy*", "*terms*"],
-                    patterns=["*advanced*"],
-                    reverse=True
-                ),
-            ]
-            
-            crawler_config = CrawlerRunConfig(
-                deep_crawl_strategy=BFSDeepCrawlStrategy(
-                    max_depth=2,  # Keep it shallow for testing
-                    # max_pages=5,  # Limit pages for testing
-                    filter_chain=FilterChain(filter_chain)
-                ),
-                cache_mode=CacheMode.BYPASS,
-            )
-            
-            print("\n1. Testing crawl with filters...")
-            results = await client.crawl(
-                ["https://docs.crawl4ai.com"],  # Simple test page
-                browser_config=BrowserConfig(headless=True),
-                crawler_config=crawler_config,
-            )
-            
-            if results:
-                print(f"✅ Crawl succeeded! Type: {type(results)}")
-                if hasattr(results, 'success'):
-                    print(f"✅ Results success: {results.success}")
-                    # Test that we can iterate results without JSON errors
-                    if hasattr(results, '__iter__'):
-                        for i, result in enumerate(results):
-                            if hasattr(result, 'url'):
-                                print(f"   Result {i}: {result.url[:50]}...")
-                            else:
-                                print(f"   Result {i}: {str(result)[:50]}...")
-                else:
-                    # Handle list of results
-                    print(f"✅ Got {len(results)} results")
-                    for i, result in enumerate(results[:3]):  # Show first 3
-                        print(f"   Result {i}: {result.url[:50]}...")
-            else:
-                print("❌ Crawl failed - no results returned")
-                return False
-                
-        print("\n✅ Docker client test completed successfully!")
-        return True
-        
-    except Exception as e:
-        print(f"❌ Docker client test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-async def test_with_rest_api():
-    """Test using REST API directly."""
-    print("\n" + "=" * 60)
-    print("Testing with REST API")
-    print("=" * 60)
-    
-    # Create filter configuration
-    deep_crawl_strategy_payload = {
-        "type": "BFSDeepCrawlStrategy",
-        "params": {
-            "max_depth": 2,
-            # "max_pages": 5,
-            "filter_chain": {
-                "type": "FilterChain",
-                "params": {
-                    "filters": [
-                        {
-                            "type": "URLPatternFilter",
-                            "params": {
-                                "patterns": ["*advanced*"],
-                                "reverse": True
-                            }
-                        }
-                    ]
-                }
-            }
-        }
-    }
-    
-    crawl_payload = {
-        "urls": ["https://docs.crawl4ai.com"],
-        "browser_config": {"type": "BrowserConfig", "params": {"headless": True}},
-        "crawler_config": {
-            "type": "CrawlerRunConfig",
-            "params": {
-                "deep_crawl_strategy": deep_crawl_strategy_payload,
-                "cache_mode": "bypass"
-            }
-        }
-    }
-    
-    try:
-        async with httpx.AsyncClient() as client:
-            print("\n1. Sending crawl request to REST API...")
-            response = await client.post(
-                f"{BASE_URL}crawl",
-                json=crawl_payload,
-                timeout=30
-            )
-            
-            if response.status_code == 200:
-                print(f"✅ REST API returned 200 OK")
-                data = response.json()
-                if data.get("success"):
-                    results = data.get("results", [])
-                    print(f"✅ Got {len(results)} results")
-                    for i, result in enumerate(results[:3]):
-                        print(f"   Result {i}: {result.get('url', 'unknown')[:50]}...")
-                else:
-                    print(f"❌ Crawl not successful: {data}")
-                    return False
-            else:
-                print(f"❌ REST API returned {response.status_code}")
-                print(f"   Response: {response.text[:500]}")
-                return False
-                
-        print("\n✅ REST API test completed successfully!")
-        return True
-        
-    except Exception as e:
-        print(f"❌ REST API test failed: {e}")
-        import traceback
-        traceback.print_exc()
-        return False
-
-
-async def main():
-    """Run all tests."""
-    print("\n🧪 TESTING COMPLETE FIX FOR DOCKER FILTER AND JSON ISSUES")
-    print("=" * 60)
-    print("Make sure the server is running with the updated code!")
-    print("=" * 60)
-    
-    results = []
-    
-    # Test 1: Docker client
-    docker_passed = await test_with_docker_client()
-    results.append(("Docker Client", docker_passed))
-    
-    # Test 2: REST API
-    rest_passed = await test_with_rest_api()
-    results.append(("REST API", rest_passed))
-    
-    # Summary
-    print("\n" + "=" * 60)
-    print("FINAL TEST SUMMARY")
-    print("=" * 60)
-    
-    all_passed = True
-    for test_name, passed in results:
-        status = "✅ PASSED" if passed else "❌ FAILED"
-        print(f"{test_name:20} {status}")
-        if not passed:
-            all_passed = False
-    
-    print("=" * 60)
-    if all_passed:
-        print("🎉 ALL TESTS PASSED! Both issues are fully resolved!")
-        print("\nThe fixes:")
-        print("1. Filter serialization: Fixed by not serializing private __slots__")
-        print("2. JSON serialization: Fixed by removing property descriptors from model_dump()")
-    else:
-        print("⚠️ Some tests failed. Please check the server logs for details.")
-    
-    return 0 if all_passed else 1
-
-
-if __name__ == "__main__":
-    import sys
-    sys.exit(asyncio.run(main()))

tests/docker/test_llm_params.py

@@ -1,349 +0,0 @@
-#!/usr/bin/env python3
-"""
-Test script for LLM temperature and base_url parameters in Crawl4AI Docker API.
-This demonstrates the new hierarchical configuration system:
-1. Request-level parameters (highest priority)
-2. Provider-specific environment variables
-3. Global environment variables
-4. System defaults (lowest priority)
-"""
-
-import asyncio
-import httpx
-import json
-import os
-from rich.console import Console
-from rich.panel import Panel
-from rich.syntax import Syntax
-from rich.table import Table
-
-
-console = Console()
-
-# Configuration
-BASE_URL = "http://localhost:11235"  # Docker API endpoint
-TEST_URL = "https://httpbin.org/html"     # Simple test page
-
-# --- Helper Functions ---
-
-async def check_server_health(client: httpx.AsyncClient) -> bool:
-    """Check if the server is healthy."""
-    console.print("[bold cyan]Checking server health...[/]", end="")
-    try:
-        response = await client.get("/health", timeout=10.0)
-        response.raise_for_status()
-        console.print(" [bold green]✓ Server is healthy![/]")
-        return True
-    except Exception as e:
-        console.print(f"\n[bold red]✗ Server health check failed: {e}[/]")
-        console.print(f"Is the server running at {BASE_URL}?")
-        return False
-
-def print_request(endpoint: str, payload: dict, title: str = "Request"):
-    """Pretty print the request."""
-    syntax = Syntax(json.dumps(payload, indent=2), "json", theme="monokai")
-    console.print(Panel.fit(
-        f"[cyan]POST {endpoint}[/cyan]\n{syntax}",
-        title=f"[bold blue]{title}[/]",
-        border_style="blue"
-    ))
-
-def print_response(response: dict, title: str = "Response"):
-    """Pretty print relevant parts of the response."""
-    # Extract only the relevant parts
-    relevant = {}
-    if "markdown" in response:
-        relevant["markdown"] = response["markdown"][:200] + "..." if len(response.get("markdown", "")) > 200 else response.get("markdown", "")
-    if "success" in response:
-        relevant["success"] = response["success"]
-    if "url" in response:
-        relevant["url"] = response["url"]
-    if "filter" in response:
-        relevant["filter"] = response["filter"]
-    
-    console.print(Panel.fit(
-        Syntax(json.dumps(relevant, indent=2), "json", theme="monokai"),
-        title=f"[bold green]{title}[/]",
-        border_style="green"
-    ))
-
-# --- Test Functions ---
-
-async def test_default_no_params(client: httpx.AsyncClient):
-    """Test 1: No temperature or base_url specified - uses defaults"""
-    console.rule("[bold yellow]Test 1: Default Configuration (No Parameters)[/]")
-    
-    payload = {
-        "url": TEST_URL,
-        "f": "llm",
-        "q": "What is the main heading of this page? Answer in exactly 5 words."
-    }
-    
-    print_request("/md", payload, "Request without temperature/base_url")
-    
-    try:
-        response = await client.post("/md", json=payload, timeout=30.0)
-        response.raise_for_status()
-        data = response.json()
-        print_response(data, "Response (using system defaults)")
-        console.print("[dim]→ This used system defaults or environment variables if set[/]")
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/]")
-
-async def test_request_temperature(client: httpx.AsyncClient):
-    """Test 2: Request-level temperature (highest priority)"""
-    console.rule("[bold yellow]Test 2: Request-Level Temperature[/]")
-    
-    # Test with low temperature (more focused)
-    payload_low = {
-        "url": TEST_URL,
-        "f": "llm",
-        "q": "What is the main heading? Be creative and poetic.",
-        "temperature": 0.1  # Very low - should be less creative
-    }
-    
-    print_request("/md", payload_low, "Low Temperature (0.1)")
-    
-    try:
-        response = await client.post("/md", json=payload_low, timeout=30.0)
-        response.raise_for_status()
-        data_low = response.json()
-        print_response(data_low, "Response with Low Temperature")
-        console.print("[dim]→ Low temperature (0.1) should produce focused, less creative output[/]")
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/]")
-    
-    console.print()
-    
-    # Test with high temperature (more creative)
-    payload_high = {
-        "url": TEST_URL,
-        "f": "llm",
-        "q": "What is the main heading? Be creative and poetic.",
-        "temperature": 1.5  # High - should be more creative
-    }
-    
-    print_request("/md", payload_high, "High Temperature (1.5)")
-    
-    try:
-        response = await client.post("/md", json=payload_high, timeout=30.0)
-        response.raise_for_status()
-        data_high = response.json()
-        print_response(data_high, "Response with High Temperature")
-        console.print("[dim]→ High temperature (1.5) should produce more creative, varied output[/]")
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/]")
-
-async def test_provider_override(client: httpx.AsyncClient):
-    """Test 3: Provider override with temperature"""
-    console.rule("[bold yellow]Test 3: Provider Override with Temperature[/]")
-    
-    provider = "gemini/gemini-2.5-flash-lite"
-    payload = {
-        "url": TEST_URL,
-        "f": "llm",
-        "q": "Summarize this page in one sentence.",
-        "provider": provider,  # Explicitly set provider
-        "temperature": 0.7
-    }
-    
-    print_request("/md", payload, "Provider + Temperature Override")
-    
-    try:
-        response = await client.post("/md", json=payload, timeout=30.0)
-        response.raise_for_status()
-        data = response.json()
-        print_response(data, "Response with Provider Override")
-        console.print(f"[dim]→ This explicitly uses {provider} with temperature 0.7[/]")
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/]")
-
-async def test_base_url_custom(client: httpx.AsyncClient):
-    """Test 4: Custom base_url (will fail unless you have a custom endpoint)"""
-    console.rule("[bold yellow]Test 4: Custom Base URL (Demo Only)[/]")
-    
-    payload = {
-        "url": TEST_URL,
-        "f": "llm",
-        "q": "What is this page about?",
-        "base_url": "https://api.custom-endpoint.com/v1",  # Custom endpoint
-        "temperature": 0.5
-    }
-    
-    print_request("/md", payload, "Custom Base URL Request")
-    console.print("[yellow]Note: This will fail unless you have a custom endpoint set up[/]")
-    
-    try:
-        response = await client.post("/md", json=payload, timeout=10.0)
-        response.raise_for_status()
-        data = response.json()
-        print_response(data, "Response from Custom Endpoint")
-    except httpx.HTTPStatusError as e:
-        console.print(f"[yellow]Expected failure (no custom endpoint): Status {e.response.status_code}[/]")
-    except Exception as e:
-        console.print(f"[yellow]Expected error: {e}[/]")
-
-async def test_llm_job_endpoint(client: httpx.AsyncClient):
-    """Test 5: Test the /llm/job endpoint with temperature and base_url"""
-    console.rule("[bold yellow]Test 5: LLM Job Endpoint with Parameters[/]")
-    
-    payload = {
-        "url": TEST_URL,
-        "q": "Extract the main title and any key information",
-        "temperature": 0.3,
-        # "base_url": "https://api.openai.com/v1"  # Optional
-    }
-    
-    print_request("/llm/job", payload, "LLM Job with Temperature")
-    
-    try:
-        # Submit the job
-        response = await client.post("/llm/job", json=payload, timeout=30.0)
-        response.raise_for_status()
-        job_data = response.json()
-        
-        if "task_id" in job_data:
-            task_id = job_data["task_id"]
-            console.print(f"[green]Job created with task_id: {task_id}[/]")
-            
-            # Poll for result (simplified - in production use proper polling)
-            await asyncio.sleep(3)
-            
-            status_response = await client.get(f"/llm/job/{task_id}")
-            status_data = status_response.json()
-            
-            if status_data.get("status") == "completed":
-                console.print("[green]Job completed successfully![/]")
-                if "result" in status_data:
-                    console.print(Panel.fit(
-                        Syntax(json.dumps(status_data["result"], indent=2), "json", theme="monokai"),
-                        title="Extraction Result",
-                        border_style="green"
-                    ))
-            else:
-                console.print(f"[yellow]Job status: {status_data.get('status', 'unknown')}[/]")
-        else:
-            console.print(f"[red]Unexpected response: {job_data}[/]")
-            
-    except Exception as e:
-        console.print(f"[red]Error: {e}[/]")
-
-
-async def test_llm_endpoint(client: httpx.AsyncClient):
-    """
-    Quick QA round-trip with /llm.
-    Asks a trivial question against SIMPLE_URL just to show wiring.
-    """
-    import time
-    import urllib.parse
-
-    page_url = "https://kidocode.com"
-    question = "What is the title of this page?"
-
-    enc = urllib.parse.quote_plus(page_url, safe="")
-    console.print(f"GET /llm/{enc}?q={question}")
-
-    try:
-        t0 = time.time()
-        resp = await client.get(f"/llm/{enc}", params={"q": question})
-        dt = time.time() - t0
-        console.print(
-            f"Response Status: [bold {'green' if resp.is_success else 'red'}]{resp.status_code}[/] (took {dt:.2f}s)")
-        resp.raise_for_status()
-        answer = resp.json().get("answer", "")
-        console.print(Panel(answer or "No answer returned",
-                      title="LLM answer", border_style="magenta", expand=False))
-    except Exception as e:
-        console.print(f"[bold red]Error hitting /llm:[/] {e}")
-
-
-async def show_environment_info():
-    """Display current environment configuration"""
-    console.rule("[bold cyan]Current Environment Configuration[/]")
-    
-    table = Table(title="LLM Environment Variables", show_header=True, header_style="bold magenta")
-    table.add_column("Variable", style="cyan", width=30)
-    table.add_column("Value", style="yellow")
-    table.add_column("Description", style="dim")
-    
-    env_vars = [
-        ("LLM_PROVIDER", "Global default provider"),
-        ("LLM_TEMPERATURE", "Global default temperature"),
-        ("LLM_BASE_URL", "Global custom API endpoint"),
-        ("OPENAI_API_KEY", "OpenAI API key"),
-        ("OPENAI_TEMPERATURE", "OpenAI-specific temperature"),
-        ("OPENAI_BASE_URL", "OpenAI-specific endpoint"),
-        ("ANTHROPIC_API_KEY", "Anthropic API key"),
-        ("ANTHROPIC_TEMPERATURE", "Anthropic-specific temperature"),
-        ("GROQ_API_KEY", "Groq API key"),
-        ("GROQ_TEMPERATURE", "Groq-specific temperature"),
-    ]
-    
-    for var, desc in env_vars:
-        value = os.environ.get(var, "[not set]")
-        if "API_KEY" in var and value != "[not set]":
-            # Mask API keys for security
-            value = value[:10] + "..." if len(value) > 10 else "***"
-        table.add_row(var, value, desc)
-    
-    console.print(table)
-    console.print()
-
-# --- Main Test Runner ---
-
-async def main():
-    """Run all tests"""
-    console.print(Panel.fit(
-        "[bold cyan]Crawl4AI LLM Parameters Test Suite[/]\n" +
-        "Testing temperature and base_url configuration hierarchy",
-        border_style="cyan"
-    ))
-    
-    # Show current environment
-    # await show_environment_info()
-    
-    # Create HTTP client
-    async with httpx.AsyncClient(base_url=BASE_URL, timeout=60.0) as client:
-        # Check server health
-        if not await check_server_health(client):
-            console.print("[red]Server is not available. Please ensure the Docker container is running.[/]")
-            return
-        
-        # Run tests
-        tests = [
-            ("Default Configuration", test_default_no_params),
-            ("Request Temperature", test_request_temperature),
-            ("Provider Override", test_provider_override),
-            ("Custom Base URL", test_base_url_custom),
-            ("LLM Job Endpoint", test_llm_job_endpoint),
-            ("LLM Endpoint", test_llm_endpoint),
-        ]
-        
-        for i, (name, test_func) in enumerate(tests, 1):
-            if i > 1:
-                console.print()  # Add spacing between tests
-            
-            try:
-                await test_func(client)
-            except Exception as e:
-                console.print(f"[red]Test '{name}' failed with error: {e}[/]")
-                console.print_exception(show_locals=False)
-        
-        console.rule("[bold green]All Tests Complete![/]", style="green")
-        
-        # Summary
-        console.print("\n[bold cyan]Configuration Hierarchy Summary:[/]")
-        console.print("1. [yellow]Request parameters[/] - Highest priority (temperature, base_url in API call)")
-        console.print("2. [yellow]Provider-specific env[/] - e.g., OPENAI_TEMPERATURE, GROQ_BASE_URL")
-        console.print("3. [yellow]Global env variables[/] - LLM_TEMPERATURE, LLM_BASE_URL")
-        console.print("4. [yellow]System defaults[/] - Lowest priority (provider/litellm defaults)")
-        console.print()
-
-if __name__ == "__main__":
-    try:
-        asyncio.run(main())
-    except KeyboardInterrupt:
-        console.print("\n[yellow]Tests interrupted by user.[/]")
-    except Exception as e:
-        console.print(f"\n[bold red]An error occurred:[/]")
-        console.print_exception(show_locals=False)

tests/test_webhook_feature.sh

@@ -0,0 +1,305 @@
+#!/bin/bash
+
+#############################################################################
+# Webhook Feature Test Script
+#
+# This script tests the webhook feature implementation by:
+# 1. Switching to the webhook feature branch
+# 2. Installing dependencies
+# 3. Starting the server
+# 4. Running webhook tests
+# 5. Cleaning up and returning to original branch
+#
+# Usage: ./test_webhook_feature.sh
+#############################################################################
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Configuration
+BRANCH_NAME="claude/implement-webhook-crawl-feature-011CULZY1Jy8N5MUkZqXkRVp"
+VENV_PATH="venv"
+SERVER_PORT=11235
+WEBHOOK_PORT=8080
+PROJECT_ROOT="$(cd "$(dirname "$0")/.." && pwd)"
+
+# PID files for cleanup
+REDIS_PID=""
+SERVER_PID=""
+WEBHOOK_PID=""
+
+#############################################################################
+# Utility Functions
+#############################################################################
+
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+cleanup() {
+    log_info "Starting cleanup..."
+
+    # Kill webhook receiver if running
+    if [ ! -z "$WEBHOOK_PID" ] && kill -0 $WEBHOOK_PID 2>/dev/null; then
+        log_info "Stopping webhook receiver (PID: $WEBHOOK_PID)..."
+        kill $WEBHOOK_PID 2>/dev/null || true
+    fi
+
+    # Kill server if running
+    if [ ! -z "$SERVER_PID" ] && kill -0 $SERVER_PID 2>/dev/null; then
+        log_info "Stopping server (PID: $SERVER_PID)..."
+        kill $SERVER_PID 2>/dev/null || true
+    fi
+
+    # Kill Redis if running
+    if [ ! -z "$REDIS_PID" ] && kill -0 $REDIS_PID 2>/dev/null; then
+        log_info "Stopping Redis (PID: $REDIS_PID)..."
+        kill $REDIS_PID 2>/dev/null || true
+    fi
+
+    # Also kill by port if PIDs didn't work
+    lsof -ti:$SERVER_PORT | xargs kill -9 2>/dev/null || true
+    lsof -ti:$WEBHOOK_PORT | xargs kill -9 2>/dev/null || true
+    lsof -ti:6379 | xargs kill -9 2>/dev/null || true
+
+    # Return to original branch
+    if [ ! -z "$ORIGINAL_BRANCH" ]; then
+        log_info "Switching back to branch: $ORIGINAL_BRANCH"
+        git checkout $ORIGINAL_BRANCH 2>/dev/null || true
+    fi
+
+    log_success "Cleanup complete"
+}
+
+# Set trap to cleanup on exit
+trap cleanup EXIT INT TERM
+
+#############################################################################
+# Main Script
+#############################################################################
+
+log_info "Starting webhook feature test script"
+log_info "Project root: $PROJECT_ROOT"
+
+cd "$PROJECT_ROOT"
+
+# Step 1: Save current branch and fetch PR
+log_info "Step 1: Fetching PR branch..."
+ORIGINAL_BRANCH=$(git rev-parse --abbrev-ref HEAD)
+log_info "Current branch: $ORIGINAL_BRANCH"
+
+git fetch origin $BRANCH_NAME
+log_success "Branch fetched"
+
+# Step 2: Switch to new branch
+log_info "Step 2: Switching to branch: $BRANCH_NAME"
+git checkout $BRANCH_NAME
+log_success "Switched to webhook feature branch"
+
+# Step 3: Activate virtual environment
+log_info "Step 3: Activating virtual environment..."
+if [ ! -d "$VENV_PATH" ]; then
+    log_error "Virtual environment not found at $VENV_PATH"
+    log_info "Creating virtual environment..."
+    python3 -m venv $VENV_PATH
+fi
+
+source $VENV_PATH/bin/activate
+log_success "Virtual environment activated: $(which python)"
+
+# Step 4: Install server dependencies
+log_info "Step 4: Installing server dependencies..."
+pip install -q -r deploy/docker/requirements.txt
+log_success "Dependencies installed"
+
+# Check if Redis is available
+log_info "Checking Redis availability..."
+if ! command -v redis-server &> /dev/null; then
+    log_warning "Redis not found, attempting to install..."
+    if command -v apt-get &> /dev/null; then
+        sudo apt-get update && sudo apt-get install -y redis-server
+    elif command -v brew &> /dev/null; then
+        brew install redis
+    else
+        log_error "Cannot install Redis automatically. Please install Redis manually."
+        exit 1
+    fi
+fi
+
+# Step 5: Start Redis in background
+log_info "Step 5a: Starting Redis..."
+redis-server --port 6379 --daemonize yes
+sleep 2
+REDIS_PID=$(pgrep redis-server)
+log_success "Redis started (PID: $REDIS_PID)"
+
+# Step 5b: Start server in background
+log_info "Step 5b: Starting server on port $SERVER_PORT..."
+cd deploy/docker
+
+# Start server in background
+python3 -m uvicorn server:app --host 0.0.0.0 --port $SERVER_PORT > /tmp/crawl4ai_server.log 2>&1 &
+SERVER_PID=$!
+cd "$PROJECT_ROOT"
+
+log_info "Server started (PID: $SERVER_PID)"
+
+# Wait for server to be ready
+log_info "Waiting for server to be ready..."
+for i in {1..30}; do
+    if curl -s http://localhost:$SERVER_PORT/health > /dev/null 2>&1; then
+        log_success "Server is ready!"
+        break
+    fi
+    if [ $i -eq 30 ]; then
+        log_error "Server failed to start within 30 seconds"
+        log_info "Server logs:"
+        tail -50 /tmp/crawl4ai_server.log
+        exit 1
+    fi
+    echo -n "."
+    sleep 1
+done
+echo ""
+
+# Step 6: Create and run webhook test
+log_info "Step 6: Creating webhook test script..."
+
+cat > /tmp/test_webhook.py << 'PYTHON_SCRIPT'
+import requests
+import json
+import time
+from flask import Flask, request, jsonify
+from threading import Thread, Event
+
+# Configuration
+CRAWL4AI_BASE_URL = "http://localhost:11235"
+WEBHOOK_BASE_URL = "http://localhost:8080"
+
+# Flask app for webhook receiver
+app = Flask(__name__)
+webhook_received = Event()
+webhook_data = {}
+
+@app.route('/webhook', methods=['POST'])
+def handle_webhook():
+    global webhook_data
+    webhook_data = request.json
+    webhook_received.set()
+    print(f"\n✅ Webhook received: {json.dumps(webhook_data, indent=2)}")
+    return jsonify({"status": "received"}), 200
+
+def start_webhook_server():
+    app.run(host='0.0.0.0', port=8080, debug=False, use_reloader=False)
+
+# Start webhook server in background
+webhook_thread = Thread(target=start_webhook_server, daemon=True)
+webhook_thread.start()
+time.sleep(2)
+
+print("🚀 Submitting crawl job with webhook...")
+
+# Submit job with webhook
+payload = {
+    "urls": ["https://example.com"],
+    "browser_config": {"headless": True},
+    "crawler_config": {"cache_mode": "bypass"},
+    "webhook_config": {
+        "webhook_url": f"{WEBHOOK_BASE_URL}/webhook",
+        "webhook_data_in_payload": True
+    }
+}
+
+response = requests.post(
+    f"{CRAWL4AI_BASE_URL}/crawl/job",
+    json=payload,
+    headers={"Content-Type": "application/json"}
+)
+
+if not response.ok:
+    print(f"❌ Failed to submit job: {response.text}")
+    exit(1)
+
+task_id = response.json()['task_id']
+print(f"✅ Job submitted successfully, task_id: {task_id}")
+
+# Wait for webhook (with timeout)
+print("⏳ Waiting for webhook notification...")
+if webhook_received.wait(timeout=60):
+    print(f"✅ Webhook received!")
+    print(f"   Task ID: {webhook_data.get('task_id')}")
+    print(f"   Status: {webhook_data.get('status')}")
+    print(f"   URLs: {webhook_data.get('urls')}")
+
+    if webhook_data.get('status') == 'completed':
+        if 'data' in webhook_data:
+            print(f"   ✅ Data included in webhook payload")
+            results = webhook_data['data'].get('results', [])
+            if results:
+                print(f"   📄 Crawled {len(results)} URL(s)")
+                for result in results:
+                    print(f"      - {result.get('url')}: {len(result.get('markdown', ''))} chars")
+        print("\n🎉 Webhook test PASSED!")
+        exit(0)
+    else:
+        print(f"   ❌ Job failed: {webhook_data.get('error')}")
+        exit(1)
+else:
+    print("❌ Webhook not received within 60 seconds")
+    # Try polling as fallback
+    print("⏳ Trying to poll job status...")
+    for i in range(10):
+        status_response = requests.get(f"{CRAWL4AI_BASE_URL}/crawl/job/{task_id}")
+        if status_response.ok:
+            status = status_response.json()
+            print(f"   Status: {status.get('status')}")
+            if status.get('status') in ['completed', 'failed']:
+                break
+        time.sleep(2)
+    exit(1)
+PYTHON_SCRIPT
+
+# Install Flask for webhook receiver
+pip install -q flask
+
+# Run the webhook test
+log_info "Running webhook test..."
+python3 /tmp/test_webhook.py &
+WEBHOOK_PID=$!
+
+# Wait for test to complete
+wait $WEBHOOK_PID
+TEST_EXIT_CODE=$?
+
+# Step 7: Verify results
+log_info "Step 7: Verifying test results..."
+if [ $TEST_EXIT_CODE -eq 0 ]; then
+    log_success "✅ Webhook test PASSED!"
+else
+    log_error "❌ Webhook test FAILED (exit code: $TEST_EXIT_CODE)"
+    log_info "Server logs:"
+    tail -100 /tmp/crawl4ai_server.log
+    exit 1
+fi
+
+# Step 8: Cleanup happens automatically via trap
+log_success "All tests completed successfully! 🎉"
+log_info "Cleanup will happen automatically..."