如何为 Crawl4AI 自托管 Docker 服务配置 webhook 回调接收爬取完成通知【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiCrawl4AI 的 Docker 版 API 服务deploy/docker通过POST /crawl/job提交异步爬取任务。默认用法是客户端拿回task_id后反复轮询GET /crawl/job/{task_id}检查状态对于长时间运行的爬取或需要避免占用连接的场景服务内置了 webhook 功能任务完成或失败后服务端会主动向你的回调端点 POST 一条通知不再需要轮询。本文基于deploy/docker目录下的部署文档完成三件事配置回调地址按任务或全局默认两种粒度、编写一个能接收通知的回调端点、以及验证通知确实送达并排查投递问题。前提条件API 服务已按 deploy/docker/README.md 启动默认监听127.0.0.1:11235回调端点必须能被服务端访问到并返回 HTTP 2xx 状态码。webhook 的工作流程按 README.md 的 “Asynchronous Jobs with Webhooks” 一节整个过程是五步提交任务POST /crawl/job请求体中携带可选的webhook_config立即拿到task_id任务在后台执行服务端把完成通知 POST 到你的 webhook 地址如果通知里没有带数据再用GET /crawl/job/{task_id}拉取结果。同一套 webhook 机制同时支持/crawl/job爬取和/llm/jobLLM 抽取两个端点。全局配置config.yml 的 webhooks 段发布版 config.yml 已经自带webhooks段无需手工创建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各字段的作用enabled总开关。设为false时任务照常运行但不会发送任何通知default_url全局默认回调地址null表示不设置。只有当请求体没带webhook_config或其中没有webhook_url时才会用到它data_in_payload通知里是否携带爬取结果的默认值可被单个任务的webhook_data_in_payload覆盖retry重试策略默认最多 5 次指数退避 1s → 2s → 4s → 8s → 16s单次调用超时 30 秒headers每次投递默认附加的请求头任务级webhook_headers会与它合并后一起发送。如果希望所有没单独指定回调的任务都通知到同一地址只需把default_url改成你的回调端点webhooks: enabled: true default_url: https://myapp.com/webhooks/default data_in_payload: false之后不带webhook_config的任务也会自动发 webhook。配置改动后需要让服务重新加载config.yml。主路径按任务提交 webhook_config最常用的是在提交任务的请求体里直接带上webhook_config粒度是单个任务curl -X POST http://localhost:11235/crawl/job \ -H Content-Type: application/json \ -d { urls: [https://example.com], webhook_config: { webhook_url: https://your-app.example.com/webhooks/crawl-complete, webhook_data_in_payload: false } }其中webhook_url需要替换成你自己的回调端点文档示例中的https://myapp.com/webhooks/crawl-complete只是样例值。webhook_url是必填字段会被校验为合法 URLwebhook_data_in_payload默认false决定通知里是否携带完整结果webhook_headers可选见下文。提交成功后响应立即返回任务 ID文档示例输出{ task_id: crawl_a1b2c3d4 }模式一只发通知凭 task_id 拉结果webhook_data_in_payload: false时回调收到的通知体文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: completed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com] }你的回调处理器拿到task_id后再调用结果接口取数据curl http://localhost:11235/crawl/job/crawl_a1b2c3d4模式二把爬取结果直接放进通知把webhook_data_in_payload设为true通知体会多出一个data字段包含完整结果文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: completed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com], data: { markdown: ..., html: ..., links: {...}, metadata: {...} } }两种模式按团队习惯选只发通知、处理器再拉取实现最简单直接带数据则省去一次往返但通知体可能较大。可选自定义请求头做鉴权webhook_headers用于在通知里附加鉴权或标识头服务端会把它与config.yml的默认头合并后发送{ 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 } } }头字段有校验限制schemas.py 中WebhookConfig在提交时执行违规请求会被 422 拒绝最多 20 个头头名只允许字母、数字、连字符且不超过 64 字符host、content-length、transfer-encoding、connection、content-type、proxy-authorization、authorization、cookie、expect、upgrade、te、trailer这些名称被禁止头值不超过 2048 字符且不能包含\r、\n、\0。回调端点示例WEBHOOK_EXAMPLES.md 提供了一个 Flask 处理器示例下面保留其中处理爬取任务的部分文档中的完整版本还处理 LLM 抽取任务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] status payload[status] if status completed: # If data not in payload, fetch it if data not in payload: response requests.get(fhttp://localhost:11235/crawl/job/{task_id}) data response.json() else: data payload[data] results data.get(results, []) for result in results: print(f - {result.get(url)}: {len(result.get(markdown, ))} chars) elif status failed: error payload.get(error, Unknown error) print(fcrawl job {task_id} failed: {error}) return jsonify({status: received}), 200 if __name__ __main__: app.run(port8080)两个注意点示例里用http://localhost:11235拉取结果只在回调服务与 API 服务运行在同一主机上成立回调端点在别的机器时要替换成实际可达的 API 地址最后一行返回 200 是关键只有收到 2xx服务端才认为投递成功。返回 4xx 会被视为拒绝且不再重试见下文重试机制。验证通知是否送达1. 提交返回 task_id回调端点收到 POST任务完成或失败后你的端点应收到一次 POST。status只有completed和failed两种值失败时通知体会多一个error字段文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: failed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com], error: Connection timeout after 30s }2. 检查服务端投递日志投递过程会写入应用日志INFO 级别记录成功投递、重试及最终失败。按文档给出的方式过滤docker logs crawl4ai-container | grep -i webhook其中crawl4ai-container需替换为你的实际容器名。webhook.py 中对应的日志信息包括Webhook delivered successfully投递成功、Webhook rejected with status {status}被 4xx 拒绝不重试、Webhook failed with status {status}, will retry5xx 将重试、Webhook blocked (SSRF protection)出站校验拦截不重试。如果两端都没收到通知先确认webhooks.enabled为true且任务请求带了webhook_config或全局配置了default_url——两者都没有时服务会静默跳过通知任务本身照常运行。3. 重试机制决定了“收不到”的语义webhook 投递采用指数退避重试WEBHOOK_EXAMPLES.md “Retry Logic” 一节项值尝试次数默认最多 5 次退避间隔1s → 2s → 4s → 8s → 16s单次超时30 秒会重试的情况5xx 状态码、网络错误、超时不重试的情况4xx 状态码记为拒绝、2xx投递成功也就是说回调端点如果暂时不可用服务端最长会在约 31 秒内尝试 5 次如果端点返回 4xx服务端会立即放弃不会再次投递。回调地址可达性出站校验限制服务端对 webhook 目标有出站校验webhook.py 与 egress_broker.py发送前会解析目标主机名若解析结果不是全局可路由地址回环、私有网段、链路本地等或主机名属于localhost、metadata、kubernetes.default、host.docker.internal等被拒名单通知会被直接丢弃并记录Webhook blocked (SSRF protection)且不重试。重定向会被逐跳重新校验最多跟随 5 跳。实际影响回调端点应部署在可被公网或至少是全局可路由地址访问的位置把webhook_url指向内网 IP 会静默收不到通知只能从日志里发现。源码中提供了CRAWL4AI_ALLOW_INTERNAL_URLS环境变量默认false可跳过该限制注释明确它只适用于受信任的内部部署。可选LLM 抽取任务/llm/job端点使用同一套webhook_configWEBHOOK_EXAMPLES.md Example 6curl -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 } }与爬取任务的区别task_type为llm_extractionurl是单值而非数组抽取结果在data.extracted_content中。文档特别提醒webhook 通知里的键是extracted_content而通过 API 拉取结果时对应的键是result处理器里两者都要兼容。限制与注意事项任务数据存放在 Redis 中config.yml默认task_ttl_seconds: 36001 小时后过期。采用“只发通知、稍后再拉结果”的模式时拉取应发生在 TTL 之内否则GET /crawl/job/{task_id}可能已经查不到数据。不配置 webhook 时轮询方式依然可用请求体省略webhook_config直接轮询GET /crawl/job/{task_id}响应中status字段取值为processing、completed或failed。若回调端点在别的机器上示例中的http://localhost:11235结果拉取地址、以及服务自身监听地址默认127.0.0.1:11235对外暴露需配置CRAWL4AI_API_TOKEN并加反向代理见config.yml注释都要按实际部署调整。配置完成后用一次真实任务闭环验证提交带webhook_config的任务 → 回调端点收到status: completed的通知 →docker logs中能看到Webhook delivered successfully。这三点都满足说明 webhook 回调链路已经打通。更完整的处理器示例含 TypeScript 客户端、完整 Flask 代码可参考 WEBHOOK_EXAMPLES.md。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 如何为 Crawl4AI 自托管 Docker 服务配置 webhook 回调接收爬取完成通知
如何为 Crawl4AI 自托管 Docker 服务配置 webhook 回调接收爬取完成通知【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4aiCrawl4AI 的 Docker 版 API 服务deploy/docker通过POST /crawl/job提交异步爬取任务。默认用法是客户端拿回task_id后反复轮询GET /crawl/job/{task_id}检查状态对于长时间运行的爬取或需要避免占用连接的场景服务内置了 webhook 功能任务完成或失败后服务端会主动向你的回调端点 POST 一条通知不再需要轮询。本文基于deploy/docker目录下的部署文档完成三件事配置回调地址按任务或全局默认两种粒度、编写一个能接收通知的回调端点、以及验证通知确实送达并排查投递问题。前提条件API 服务已按 deploy/docker/README.md 启动默认监听127.0.0.1:11235回调端点必须能被服务端访问到并返回 HTTP 2xx 状态码。webhook 的工作流程按 README.md 的 “Asynchronous Jobs with Webhooks” 一节整个过程是五步提交任务POST /crawl/job请求体中携带可选的webhook_config立即拿到task_id任务在后台执行服务端把完成通知 POST 到你的 webhook 地址如果通知里没有带数据再用GET /crawl/job/{task_id}拉取结果。同一套 webhook 机制同时支持/crawl/job爬取和/llm/jobLLM 抽取两个端点。全局配置config.yml 的 webhooks 段发布版 config.yml 已经自带webhooks段无需手工创建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各字段的作用enabled总开关。设为false时任务照常运行但不会发送任何通知default_url全局默认回调地址null表示不设置。只有当请求体没带webhook_config或其中没有webhook_url时才会用到它data_in_payload通知里是否携带爬取结果的默认值可被单个任务的webhook_data_in_payload覆盖retry重试策略默认最多 5 次指数退避 1s → 2s → 4s → 8s → 16s单次调用超时 30 秒headers每次投递默认附加的请求头任务级webhook_headers会与它合并后一起发送。如果希望所有没单独指定回调的任务都通知到同一地址只需把default_url改成你的回调端点webhooks: enabled: true default_url: https://myapp.com/webhooks/default data_in_payload: false之后不带webhook_config的任务也会自动发 webhook。配置改动后需要让服务重新加载config.yml。主路径按任务提交 webhook_config最常用的是在提交任务的请求体里直接带上webhook_config粒度是单个任务curl -X POST http://localhost:11235/crawl/job \ -H Content-Type: application/json \ -d { urls: [https://example.com], webhook_config: { webhook_url: https://your-app.example.com/webhooks/crawl-complete, webhook_data_in_payload: false } }其中webhook_url需要替换成你自己的回调端点文档示例中的https://myapp.com/webhooks/crawl-complete只是样例值。webhook_url是必填字段会被校验为合法 URLwebhook_data_in_payload默认false决定通知里是否携带完整结果webhook_headers可选见下文。提交成功后响应立即返回任务 ID文档示例输出{ task_id: crawl_a1b2c3d4 }模式一只发通知凭 task_id 拉结果webhook_data_in_payload: false时回调收到的通知体文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: completed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com] }你的回调处理器拿到task_id后再调用结果接口取数据curl http://localhost:11235/crawl/job/crawl_a1b2c3d4模式二把爬取结果直接放进通知把webhook_data_in_payload设为true通知体会多出一个data字段包含完整结果文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: completed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com], data: { markdown: ..., html: ..., links: {...}, metadata: {...} } }两种模式按团队习惯选只发通知、处理器再拉取实现最简单直接带数据则省去一次往返但通知体可能较大。可选自定义请求头做鉴权webhook_headers用于在通知里附加鉴权或标识头服务端会把它与config.yml的默认头合并后发送{ 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 } } }头字段有校验限制schemas.py 中WebhookConfig在提交时执行违规请求会被 422 拒绝最多 20 个头头名只允许字母、数字、连字符且不超过 64 字符host、content-length、transfer-encoding、connection、content-type、proxy-authorization、authorization、cookie、expect、upgrade、te、trailer这些名称被禁止头值不超过 2048 字符且不能包含\r、\n、\0。回调端点示例WEBHOOK_EXAMPLES.md 提供了一个 Flask 处理器示例下面保留其中处理爬取任务的部分文档中的完整版本还处理 LLM 抽取任务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] status payload[status] if status completed: # If data not in payload, fetch it if data not in payload: response requests.get(fhttp://localhost:11235/crawl/job/{task_id}) data response.json() else: data payload[data] results data.get(results, []) for result in results: print(f - {result.get(url)}: {len(result.get(markdown, ))} chars) elif status failed: error payload.get(error, Unknown error) print(fcrawl job {task_id} failed: {error}) return jsonify({status: received}), 200 if __name__ __main__: app.run(port8080)两个注意点示例里用http://localhost:11235拉取结果只在回调服务与 API 服务运行在同一主机上成立回调端点在别的机器时要替换成实际可达的 API 地址最后一行返回 200 是关键只有收到 2xx服务端才认为投递成功。返回 4xx 会被视为拒绝且不再重试见下文重试机制。验证通知是否送达1. 提交返回 task_id回调端点收到 POST任务完成或失败后你的端点应收到一次 POST。status只有completed和failed两种值失败时通知体会多一个error字段文档示例{ task_id: crawl_a1b2c3d4, task_type: crawl, status: failed, timestamp: 2025-10-21T10:30:00.00000000:00, urls: [https://example.com], error: Connection timeout after 30s }2. 检查服务端投递日志投递过程会写入应用日志INFO 级别记录成功投递、重试及最终失败。按文档给出的方式过滤docker logs crawl4ai-container | grep -i webhook其中crawl4ai-container需替换为你的实际容器名。webhook.py 中对应的日志信息包括Webhook delivered successfully投递成功、Webhook rejected with status {status}被 4xx 拒绝不重试、Webhook failed with status {status}, will retry5xx 将重试、Webhook blocked (SSRF protection)出站校验拦截不重试。如果两端都没收到通知先确认webhooks.enabled为true且任务请求带了webhook_config或全局配置了default_url——两者都没有时服务会静默跳过通知任务本身照常运行。3. 重试机制决定了“收不到”的语义webhook 投递采用指数退避重试WEBHOOK_EXAMPLES.md “Retry Logic” 一节项值尝试次数默认最多 5 次退避间隔1s → 2s → 4s → 8s → 16s单次超时30 秒会重试的情况5xx 状态码、网络错误、超时不重试的情况4xx 状态码记为拒绝、2xx投递成功也就是说回调端点如果暂时不可用服务端最长会在约 31 秒内尝试 5 次如果端点返回 4xx服务端会立即放弃不会再次投递。回调地址可达性出站校验限制服务端对 webhook 目标有出站校验webhook.py 与 egress_broker.py发送前会解析目标主机名若解析结果不是全局可路由地址回环、私有网段、链路本地等或主机名属于localhost、metadata、kubernetes.default、host.docker.internal等被拒名单通知会被直接丢弃并记录Webhook blocked (SSRF protection)且不重试。重定向会被逐跳重新校验最多跟随 5 跳。实际影响回调端点应部署在可被公网或至少是全局可路由地址访问的位置把webhook_url指向内网 IP 会静默收不到通知只能从日志里发现。源码中提供了CRAWL4AI_ALLOW_INTERNAL_URLS环境变量默认false可跳过该限制注释明确它只适用于受信任的内部部署。可选LLM 抽取任务/llm/job端点使用同一套webhook_configWEBHOOK_EXAMPLES.md Example 6curl -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 } }与爬取任务的区别task_type为llm_extractionurl是单值而非数组抽取结果在data.extracted_content中。文档特别提醒webhook 通知里的键是extracted_content而通过 API 拉取结果时对应的键是result处理器里两者都要兼容。限制与注意事项任务数据存放在 Redis 中config.yml默认task_ttl_seconds: 36001 小时后过期。采用“只发通知、稍后再拉结果”的模式时拉取应发生在 TTL 之内否则GET /crawl/job/{task_id}可能已经查不到数据。不配置 webhook 时轮询方式依然可用请求体省略webhook_config直接轮询GET /crawl/job/{task_id}响应中status字段取值为processing、completed或failed。若回调端点在别的机器上示例中的http://localhost:11235结果拉取地址、以及服务自身监听地址默认127.0.0.1:11235对外暴露需配置CRAWL4AI_API_TOKEN并加反向代理见config.yml注释都要按实际部署调整。配置完成后用一次真实任务闭环验证提交带webhook_config的任务 → 回调端点收到status: completed的通知 →docker logs中能看到Webhook delivered successfully。这三点都满足说明 webhook 回调链路已经打通。更完整的处理器示例含 TypeScript 客户端、完整 Flask 代码可参考 WEBHOOK_EXAMPLES.md。【免费下载链接】crawl4ai Crawl4AI: Open-source LLM Friendly Web Crawler Scraper. Dont be shy, join here: https://discord.gg/jP8KfhDhyN项目地址: https://gitcode.com/GitHub_Trending/craw/crawl4ai创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考