🖼️ 인포그래픽

🖼️ 4컷 인포그래픽

💡 한 줄 요약

Firecrawl은 /crawl 엔드포인트에 웹훅을 추가해 크롤 시작, 페이지별 처리, 완료, 실패 상태를 지정한 URL로 POST 전송할 수 있게 했습니다.

📌 핵심 요약

• Firecrawl Launch Week 7일 차 글은 /crawl 엔드포인트의 새로운 웹훅 지원을 소개합니다.
• 사용자는 /crawl 요청에 webhook 파라미터를 전달해 크롤 상태 변화가 발생할 때 지정한 URL로 POST 요청을 받을 수 있습니다.
• 이번 변경의 핵심은 웹훅이 최종 전체 결과만이 아니라 크롤된 각 페이지마다 트리거된다는 점입니다.
• 웹훅 이벤트는 crawl.started, crawl.page, crawl.completed, crawl.failed 네 가지로 구분됩니다.
• 응답에는 성공 여부, 이벤트 타입, 크롤 ID, 스크랩 데이터 배열, 오류 메시지 등이 포함되며 자세한 내용은 문서에서 확인하도록 안내합니다.

🧩 주요 포인트

1. Firecrawl Launch Week 7일 차 글은 /crawl 엔드포인트의 새로운 웹훅 지원을 소개합니다.
2. 사용자는 /crawl 요청에 webhook 파라미터를 전달해 크롤 상태 변화가 발생할 때 지정한 URL로 POST 요청을 받을 수 있습니다.
3. 이번 변경의 핵심은 웹훅이 최종 전체 결과만이 아니라 크롤된 각 페이지마다 트리거된다는 점입니다.
4. 웹훅 이벤트는 crawl.started, crawl.page, crawl.completed, crawl.failed 네 가지로 구분됩니다.
5. 응답에는 성공 여부, 이벤트 타입, 크롤 ID, 스크랩 데이터 배열, 오류 메시지 등이 포함되며 자세한 내용은 문서에서 확인하도록 안내합니다.

🧠 상세 정리

1. 출시 맥락과 핵심 발표

이 글은 Firecrawl Launch Week의 7일 차 발표로, 주제는 Crawl Webhooks v1입니다. 본문은 먼저 Firecrawl이 웹 데이터 수집을 무료로 시작하고 프로젝트 확장에 맞춰 사용할 수 있다고 안내한 뒤, 실제 기능 소개로 넘어갑니다. 핵심 발표는 /crawl 엔드포인트에 webhook 파라미터를 넘길 수 있게 되었다는 것입니다. 이를 통해 크롤 작업의 진행 상태를 외부 시스템이 별도 조회 없이 POST 요청으로 받을 수 있는 구조가 마련되었습니다.

2. 웹훅 파라미터와 동작 방식

새 기능에서는 사용자가 /crawl 엔드포인트 호출 시 webhook 파라미터에 원하는 URL을 지정합니다. Firecrawl은 크롤이 시작되거나 업데이트되거나 완료될 때 해당 URL로 POST 요청을 보냅니다. 특히 본문은 웹훅이 이제 전체 결과가 끝난 뒤 한 번만 실행되는 것이 아니라, 크롤된 모든 페이지마다 트리거된다고 설명합니다. 따라서 페이지 단위의 처리 흐름을 받는 쪽에서 더 세밀하게 추적할 수 있습니다.

3. 네 가지 웹훅 이벤트

본문은 새 웹훅이 네 가지 이벤트 타입을 가진다고 정리합니다. crawl.started는 크롤 작업이 시작될 때 발생하고, crawl.page는 각 페이지가 크롤될 때마다 발생합니다. crawl.completed는 크롤이 모두 끝났음을 알리기 위해 사용되며, crawl.failed는 크롤이 실패했을 때 발생합니다. 이 구분은 시작, 페이지별 진행, 정상 종료, 실패라는 크롤 생명주기를 명확히 나누는 역할을 합니다.

4. 웹훅 응답 구조

웹훅 응답에는 success, type, id, data, error 같은 필드가 포함됩니다. success는 페이지가 올바르게 크롤되었는지에 대한 성공 여부를 나타내고, type은 발생한 이벤트의 종류를 담습니다. id는 해당 크롤 작업의 식별자이며, data는 스크랩된 데이터 배열입니다. data는 crawl.page 이벤트에서만 비어 있지 않으며, 페이지가 성공적으로 스크랩되면 /scrape 엔드포인트 응답과 같은 형태의 항목 하나를 포함합니다. 실패가 발생하면 error 필드에 오류 메시지가 들어갑니다.

🧾 핵심 주장 / 시사점

• 가장 중요한 변화는 크롤 결과를 최종 일괄 응답으로만 받는 방식에서 페이지별 이벤트를 받는 방식으로 확장된 점입니다.
• 이벤트 타입과 응답 필드가 분리되어 있어 수신 시스템은 시작, 진행, 완료, 실패 상태를 각각 다르게 처리할 수 있습니다.
• data 필드가 crawl.page에서만 실질적으로 채워진다는 설명은 구현 시 이벤트 타입별 분기 처리가 필요하다는 점을 보여줍니다.

✅ 액션 아이템

• /crawl 요청에서 webhook 파라미터를 사용해 crawl.started, crawl.page, crawl.completed, crawl.failed 이벤트가 지정 URL로 POST되는 계약을 정한다.
• 이벤트 응답의 success, event, crawlId, 스크랩 데이터 배열, error 메시지를 기준으로 페이지 단위 처리 로직을 정의해 추적 로그를 남긴다.
• 각 페이지별 page 이벤트를 crawl ID와 결합해 시작·완료·실패 흐름까지 이어지는 상태 라인을 정합성 있게 점검한다.

❓ 열린 질문

• crawl.page 이벤트가 다수 발생할 때 crawl.completed 이벤트와의 상태 정합성을 어떻게 판단할 것인가?
• success 필드와 event 타입 조합으로 실패 여부를 판별할 때 오류 메시지를 어느 우선순위로 반영할 것인가?
• 페이지 단위 웹훅 수신 시 스크랩 데이터 배열의 실시간 저장과 완료 이벤트 집계를 결합하면 지연을 줄일 수 있는가?